gemvc/connection-contracts

Database connection contracts for GEMVC framework.

Package Information

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

Purpose

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

Contents

Interfaces

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

Exceptions

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

Utilities

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

Installation

composer require gemvc/connection-contracts

Usage

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();

Key Design Decisions

Return Type: ?object

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

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

Transaction Methods

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

Requirements

• PHP >= 8.1

Status

✅ Stable - Version 1.0.0

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

Architecture

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

Contributing

Contributions are welcome! Please ensure all code:

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

License

MIT License - see LICENSE file for details

---

GEMVC: PHP framework built for Microservices