PHPackages                             gemvc/connection-contracts - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. gemvc/connection-contracts

ActiveLibrary[Database & ORM](/categories/database)

gemvc/connection-contracts
==========================

Database connection contracts for GEMVC framework

1.0.1(5mo ago)01733MITPHPPHP >=8.2

Since Dec 8Pushed 5mo agoCompare

[ Source](https://github.com/gemvc/connection-contracts)[ Packagist](https://packagist.org/packages/gemvc/connection-contracts)[ Docs](https://github.com/gemvc/connection-contracts)[ RSS](/packages/gemvc-connection-contracts/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (2)Versions (3)Used By (3)

gemvc/connection-contracts
==========================

[](#gemvcconnection-contracts)

Database connection contracts for GEMVC framework.

Package Information
-------------------

[](#package-information)

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

Purpose
-------

[](#purpose)

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

Contents
--------

[](#contents)

### Interfaces

[](#interfaces)

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

### Exceptions

[](#exceptions)

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

### Utilities

[](#utilities)

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

Installation
------------

[](#installation)

```
composer require gemvc/connection-contracts
```

Usage
-----

[](#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
--------------------

[](#key-design-decisions)

### Return Type: `?object`

[](#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)

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

[](#requirements)

- PHP >= 8.1

Status
------

[](#status)

✅ **Stable** - Version 1.0.0

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

Architecture
------------

[](#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
------------

[](#contributing)

Contributions are welcome! Please ensure all code:

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

License
-------

[](#license)

MIT License - see LICENSE file for details

---

**[GEMVC: PHP framework built for Microservices](https://www.gemvc.de)**

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance72

Regular maintenance activity

Popularity11

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

161d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e56aef71be22058cb4009cb1ef3b656232c2250df6726d63a812e18fe6f73e3c?d=identicon)[gemvc](/maintainers/gemvc)

---

Top Contributors

[![gemvc](https://avatars.githubusercontent.com/u/211101824?v=4)](https://github.com/gemvc "gemvc (7 commits)")

---

Tags

interfacescontractsdatabaseConnectiongemvc

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/gemvc-connection-contracts/health.svg)

```
[![Health](https://phpackages.com/badges/gemvc-connection-contracts/health.svg)](https://phpackages.com/packages/gemvc-connection-contracts)
```

###  Alternatives

[atlas/pdo

Provides a PDO instance decorator with convenience methods, and a connection manager.

18258.0k8](/packages/atlas-pdo)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)