gemvc/connection-contracts

Database connection contracts for GEMVC framework

Maintainers

Details

github.com/gemvc/connection-contracts

Homepage

Source

Issues

Installs: 7

Dependents: 2

Suggesters: 0

Security: 0

Stars: 0

Watchers: 0

Forks: 0

Open Issues: 0

pkg:composer/gemvc/connection-contracts

1.0.1 2025-12-08 12:08 UTC

Requires

  • php: >=8.2

Requires (Dev)

MIT 3ebdab877a9633c0fa684a7386c1fd9e94470997

databaseConnectioninterfacescontractsgemvc

This package is auto-updated.

Last update: 2025-12-08 12:11:08 UTC

README

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