Database connection contracts for GEMVC framework.

• Package Name: gemvc/connection-contracts
• Namespace: Gemvc\Database\Connection\Contracts\
• Type: Contracts/Interfaces only (no implementation)

This package defines the contracts (interfaces) for database connection management across different drivers (PDO, Swoole/Hyperf, MongoDB, etc.).

• ConnectionInterface - Contract for individual database connections
• ConnectionManagerInterface - Contract for connection pool/manager

• ConnectionException - Base exception for connection errors
• ConnectionFailedException - Connection failure exception
• TransactionException - Transaction-related exception

• ConnectionManagerAdapter - Framework-agnostic adapter for wrapping legacy managers
• ConnectionManagerFactory - Factory for creating connection managers from legacy implementations

composer require gemvc/connection-contracts

use Gemvc\Database\Connection\Contracts\ConnectionInterface;
use Gemvc\Database\Connection\Contracts\ConnectionManagerInterface;
// Get connection from manager
$manager = /* ... */;
$connection = $manager->getConnection();
if ($connection === null) {
 // Handle connection failure
 return;
}
// Get underlying driver object
$driver = $connection->getConnection(); // Returns ?object
// Type check for specific driver (required for PHPStan Level 9)
if ($driver instanceof \PDO) {
 // Use PDO methods
 $stmt = $driver->prepare('SELECT * FROM users');
} elseif ($driver instanceof \MongoDB\Client) {
 // Use MongoDB methods
 $collection = $driver->selectDatabase('mydb')->selectCollection('users');
}
// Transactions (on connection, not manager)
$connection->beginTransaction();
// ... do work ...
$connection->commit();

The ConnectionInterface::getConnection() method returns ?object (not mixed) for:

• Better type safety
• PHPStan Level 9 compliance
• Future extensibility (supports PDO, MongoDB, etc.)

Transaction methods (beginTransaction, commit, rollback, inTransaction) are defined in ConnectionInterface, NOT in ConnectionManagerInterface.

Rationale: Single Responsibility Principle (SRP) and Dependency Inversion Principle (DIP)

• Manager manages pool lifecycle
• Connection executes operations

• PHP >= 8.1

✅ Stable - Version 1.0.0

This package is production-ready and follows SOLID principles with PHPStan Level 9 compliance.

This package implements a clean separation of concerns:

• ConnectionManagerInterface: Manages connection pool lifecycle (get/release connections)
• ConnectionInterface: Handles connection operations (queries, transactions)
• Exceptions: Comprehensive exception hierarchy for error handling

This design follows:

• Single Responsibility Principle (SRP): Manager handles pools, Connection handles operations
• Dependency Inversion Principle (DIP): Depend on abstractions, not concretions

Contributions are welcome! Please ensure all code:

• Passes PHPStan Level 9 analysis
• Includes unit and integration tests
• Follows PSR-12 coding standards

MIT License - see LICENSE file for details

GEMVC: PHP framework built for Microservices