Download the PHP package gemvc/connection-pdo without Composer

gemvc/connection-pdo

PDO connection library implementation package for GEMVC framework.

Package Information

• Package Name: gemvc/connection-pdo
• Namespace: Gemvc\Database\Connection\Pdo\
• Type: PDO connection implementation package
• Environment: Apache/Nginx PHP-FPM (simple connections)
• Framework-Specific: No - This package is framework-agnostic (only depends on connection-contracts)
• Depends On: gemvc/connection-contracts: ^1.0

Purpose

This package provides PDO connection implementation for GEMVC framework:

1. PdoConnection - Real implementation that creates actual PDO connections

   • Creates: new PDO($dsn, $user, $pass) - REAL IMPLEMENTATION
   • Implements: ConnectionManagerInterface (from connection-contracts package)
   • Used by: Framework's connection management system
   • Supports multiple database drivers:
     • MySQL (default, primary) - Optimized with MySQL-specific features
     • PostgreSQL - Optimized with PostgreSQL-specific defaults and SSL support
     • SQLite - Supported for testing and development
     • Other PDO drivers - via standard DSN format
2. PdoConnectionAdapter - Adapter that wraps PDO instances
   • Wraps: Existing PDO instances (doesn't create them)
   • Implements: ConnectionInterface (from connection-contracts package)
   • Used by: PdoConnection to wrap created PDO instances

It's designed for traditional PHP-FPM environments where each request gets its own PHP process.

Features

• ✅ Real Implementation: Creates actual PDO connections (PdoConnection)
• ✅ Adapter: Wraps PDO instances for contracts (PdoConnectionAdapter)
• ✅ Multi-Driver Support: MySQL (default), PostgreSQL, SQLite, and other PDO drivers
• ✅ MySQL Optimizations: Charset/collation setup, buffered queries, strict SQL mode
• ✅ PostgreSQL Optimizations: Driver-specific defaults (port, user, charset), SSL mode support
• ✅ Simple PDO connection management
• ✅ Transaction support (begin, commit, rollback)
• ✅ Error handling
• ✅ Connection state tracking
• ✅ Implements ConnectionManagerInterface (real implementation)
• ✅ Implements ConnectionInterface (adapter)

Installation

Dependencies

Required

• php >= 8.2
• gemvc/connection-contracts: ^1.0 - For ConnectionInterface

Framework Dependencies (Runtime)

• None - This package only depends on connection-contracts package
• Reads environment variables directly from $_ENV (no framework helpers needed)

Note: This package is framework-agnostic and only depends on connection-contracts. The framework should ensure $_ENV is populated before using this package.

Usage

Using the Real Implementation

MySQL (Default)

PostgreSQL

Note: PostgreSQL uses driver-specific defaults: port 5432, username postgres, charset UTF8. Unlike MySQL, PostgreSQL's PDO DSN does not support a charset parameter — charset/encoding is applied via SET NAMES immediately after connecting instead.

SQLite (for Testing/Development)

Programmatic Configuration Override (for CLI/Docker)

For CLI commands in dockerized applications where you need to override database configuration:

Note: setConfig() clears any cached connections and DSN, ensuring new connections use the updated configuration.

Using the Adapter

Architecture

This package provides two components that work together with connection-contracts:

1. PdoConnection - Real Implementation

Creates actual PDO connections:

• Creates: new PDO($dsn, $user, $pass) - REAL IMPLEMENTATION
• Implements: ConnectionManagerInterface (from connection-contracts package)
• Manages connection lifecycle
• Handles configuration from environment variables
• Returns: ConnectionInterface (wrapped PDO via PdoConnectionAdapter)
• Simple connection caching (one connection per name, within request)
• No framework dependencies - reads $_ENV directly

Database Driver Support:

• MySQL (default): Primary driver with optimizations (charset, collation, strict mode)
• PostgreSQL: Optimized driver with driver-specific defaults (port, user, charset) and SSL mode support
• SQLite: Supported for testing/development (uses :memory: or file path)
• Other PDO drivers: via standard DSN format

Configuration Methods:

1. Environment Variables (default): Reads from $_ENV
2. Programmatic Override: Use setConfig() method to override programmatically (useful for CLI/docker)

Environment Variables:

• DB_DRIVER - Database driver (default: mysql, supports: mysql, pgsql, sqlite, etc.)
• DB_HOST - Database host (default: localhost, not used for SQLite)
• DB_PORT - Database port (driver-specific default: 3306 for MySQL/others, 5432 for PostgreSQL; not used for SQLite)
• DB_NAME - Database name (default: gemvc_db, for SQLite use :memory: or file path)
• DB_USER - Database username (driver-specific default: root for MySQL/others, postgres for PostgreSQL; not used for SQLite)
• DB_PASSWORD - Database password (default: empty, not used for SQLite)
• DB_CHARSET - Database charset (driver-specific default: utf8mb4 for MySQL, UTF8 for PostgreSQL)
• DB_COLLATION - Database collation (default: utf8mb4_unicode_ci, MySQL only - not applicable to PostgreSQL)
• DB_SSLMODE - SSL mode, e.g. require, verify-full (optional, PostgreSQL only)
• DB_PERSISTENT_CONNECTIONS - Enable persistent connections (default: 1 - enabled, MySQL/PostgreSQL)
• DB_CONNECTION_TIMEOUT - Connection timeout in seconds (default: 5, MySQL/PostgreSQL)
• APP_ENV - Application environment (optional, used for dev logging)

Programmatic Configuration Methods:

• setConfig(array $config): void - Override configuration programmatically
  • Clears cached connections and DSN
  • Useful for CLI commands in dockerized applications
  • All config keys are optional (uses defaults if not provided)
  • Example: $manager->setConfig(['host' => 'mysql-container', 'database' => 'my_db'])
• resetConfig(): void - Reset configuration back to $_ENV values

2. PdoConnectionAdapter - Adapter

Wraps existing PDO instances:

• Wraps: Existing PDO instances (doesn't create them)
• Implements: ConnectionInterface (from connection-contracts package)
• Provides transaction management (on Connection, not Manager)
• Error handling and state tracking
• Used by: PdoConnection to wrap created PDO instances

Complete Flow

Integration with connection-contracts

• PdoConnection implements ConnectionManagerInterface (from contracts)
• PdoConnectionAdapter implements ConnectionInterface (from contracts)
• Result: Complete implementation of connection contracts, framework-agnostic

Testing

Running Tests

Test Coverage

The package includes comprehensive test coverage:

• Overall Coverage: 100.00% lines, 100.00% methods
• PdoConnection: 100.00% lines, 100.00% methods
• PdoConnectionAdapter: 100.00% lines, 100.00% methods
• Total Tests: 153 tests with 438 assertions

Test Classes

• PdoConnectionTest - Unit tests for PdoConnection (isolated testing)
• PdoConnectionClassTest - Comprehensive test class covering all methods
• PdoConnectionIntegrationTest - Integration tests with real database operations
• PdoConnectionAdapterTest - Unit tests for PdoConnectionAdapter
• PdoConnectionAdapterIntegrationTest - Integration tests for adapter

Generating Coverage Report

The HTML report will be generated in the coverage-report/ directory.

License

MIT

Made with ❤️ by Ali Khorsandfard

This package is part of the GEMVC Repository framework ecosystem.

GEMVC is PHP framework built for Microservice.