Release Notes - v1.0.1

🎉 Stable Release

We're excited to announce the first stable release of gemvc/connection-contracts - a production-ready package that defines database connection contracts for the GEMVC framework.

📦 What's Included

Core Interfaces

• ConnectionInterface - Contract for individual database connections

  • Handles connection operations (queries, transactions)
  • Returns ?object for type-safe driver access (PDO, MongoDB, etc.)
  • Includes transaction methods: beginTransaction(), commit(), rollback(), inTransaction()
  • Error handling and initialization state management

• ConnectionManagerInterface - Contract for connection pool/manager

  • Manages connection lifecycle (get/release connections)
  • Pool statistics and error handling
  • Follows Single Responsibility Principle (SRP)

Exception Hierarchy

• ConnectionException - Base exception for all connection errors
• ConnectionFailedException - Specific exception for connection failures
• TransactionException - Exception for transaction-related errors

Utilities

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

✨ Key Features

Type Safety & PHPStan Level 9 Compliance

• Uses ?object return type (not mixed) for better type safety
• Full PHPStan Level 9 static analysis compliance
• Requires explicit type checking with instanceof for driver-specific operations

SOLID Principles

• Single Responsibility Principle (SRP): Clear separation between connection management and connection operations
• Dependency Inversion Principle (DIP): Depend on abstractions, not concretions
• Transaction methods are correctly placed on ConnectionInterface, not ConnectionManagerInterface

Multi-Driver Support

Designed to work with multiple database drivers:

• PDO (MySQL, PostgreSQL, SQLite, etc.)
• MongoDB
• Swoole/Hyperf connections
• Any custom database driver

Production Ready

• ✅ Comprehensive unit and integration tests (22 tests, 78 assertions)
• ✅ PHPStan Level 9 static analysis (zero errors)
• ✅ PSR-12 coding standards
• ✅ Full PHPDoc documentation
• ✅ MIT License
• ✅ Optimized package distribution (tests and dev files excluded from production package)

📋 Requirements

• PHP >= 8.2

🚀 Installation

composer require gemvc/connection-contracts

Note: Unit tests and development files are excluded from the distributed package to keep the package size minimal. Tests are available in the GitHub repository for contributors and development purposes.

📖 Usage Example

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

🏗️ 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

🧪 Testing

• 22 tests covering all interfaces and exceptions
• 78 assertions ensuring contract compliance
• Unit tests for individual components
• Integration tests for interface interactions

📚 Documentation

Full documentation is available in the README.md file, including:

• Detailed usage examples
• Design decisions and rationale
• Architecture overview
• Contributing guidelines

🔗 Links

• GitHub: https://github.com/gemvc/connection-contracts
• Issues: https://github.com/gemvc/connection-contracts/issues
• GEMVC Framework: https://www.gemvc.de

🙏 Credits

Developed for the GEMVC framework - PHP framework built for Microservices.

Full Changelog: This is the initial release. See the repository for complete history.

Full Changelog: 1.0.0...1.0.1

Release Notes - v1.0.0

Initial Stable Release

We're excited to announce the first stable release of gemvc/connection-contracts - a production-ready package that defines database connection contracts for the GEMVC framework.

What's Included

Core Interfaces

• ConnectionInterface - Contract for individual database connections

  • Handles connection operations (queries, transactions)
  • Returns ?object for type-safe driver access (PDO, MongoDB, etc.)
  • Includes transaction methods: beginTransaction(), commit(), rollback(), inTransaction()
  • Error handling and initialization state management

• ConnectionManagerInterface - Contract for connection pool/manager

  • Manages connection lifecycle (get/release connections)
  • Pool statistics and error handling
  • Follows Single Responsibility Principle (SRP)

Exception Hierarchy

• ConnectionException - Base exception for all connection errors
• ConnectionFailedException - Specific exception for connection failures
• TransactionException - Exception for transaction-related errors

Utilities

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

Key Features

Type Safety & PHPStan Level 9 Compliance

• Uses ?object return type (not mixed) for better type safety
• Full PHPStan Level 9 static analysis compliance
• Requires explicit type checking with instanceof for driver-specific operations

SOLID Principles

• Single Responsibility Principle (SRP): Clear separation between connection management and connection operations
• Dependency Inversion Principle (DIP): Depend on abstractions, not concretions
• Transaction methods are correctly placed on ConnectionInterface, not ConnectionManagerInterface

Multi-Driver Support

Designed to work with multiple database drivers:

• PDO (MySQL, PostgreSQL, SQLite, etc.)
• MongoDB
• Swoole/Hyperf connections
• Any custom database driver

Production Ready

• ✅ Comprehensive unit and integration tests (22 tests, 78 assertions)
• ✅ PHPStan Level 9 static analysis (zero errors)
• ✅ PSR-12 coding standards
• ✅ Full PHPDoc documentation
• ✅ MIT License

Requirements

• PHP >= 8.2

Installation

composer require gemvc/connection-contracts

Usage Example

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

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

Testing

• 22 tests covering all interfaces and exceptions
• 78 assertions ensuring contract compliance
• Unit tests for individual components
• Integration tests for interface interactions

Documentation

Full documentation is available in the README.md file, including:

• Detailed usage examples
• Design decisions and rationale
• Architecture overview
• Contributing guidelines

Links

• GitHub: https://github.com/gemvc/connection-contracts
• Issues: https://github.com/gemvc/connection-contracts/issues
• GEMVC Framework: https://www.gemvc.de

Credits

Developed for the GEMVC framework - PHP framework built for Microservices.

Full Changelog: This is the initial release. See the repository for complete history.