Download the PHP package faster-php/db without Composer

FasterPHP/Db

FasterPHP/Db is a high-performance, drop-in replacement for PHP's native PDO class. It enhances standard database operations with advanced features designed for robust, modern applications — all while retaining full compatibility with PDO interfaces and expectations.

If you're tired of dealing with intermittent MySQL timeouts or disconnects, repetitive statement preparation, or clunky connection logic, this package gives you a clean, extensible, and efficient solution that just works — no learning curve required.

Key features:

• ✅ Drop-in PDO replacement (extends PDO, not just wraps it)
• 🔁 Auto-reconnect on lost or timed-out connections with configurable retry/backoff
• 🛡️ Transaction-aware reconnect protection
• 🔄 Lazy-loading and internal connection pooling
• ⚡️ Prepared statement caching for reduced overhead
• 📝 Optional PSR-3 logging support
• 🧱 Custom DbStatement class for enhanced control

🚀 Installation

✅ Requirements

• PHP 8.2 or higher
• A supported PDO database (e.g. MySQL, PostgreSQL, SQLite, etc.)
• PDO extension (ext-pdo)

📦 Basic Usage

🔁 Auto-Reconnect

If a connection is lost (e.g. due to a timeout), FasterPhp\Db automatically reconnects, re-prepares (where necessary), and re-executes the statement.

Configurable Retry with Exponential Backoff

The DefaultStrategy supports configurable retry attempts with exponential backoff:

With these settings, reconnect attempts will wait 100ms, then 200ms, then 400ms between retries.

Transaction-Aware Reconnect Protection

Reconnecting mid-transaction would silently lose uncommitted changes. FasterPhp\Db prevents this by throwing a DbException if a reconnectable error occurs during an active transaction:

This protection works for both explicit transactions (beginTransaction()) and raw SQL transactions (BEGIN/START TRANSACTION).

PSR-3 Logging

You can attach a PSR-3 compatible logger to monitor reconnect events:

Custom Reconnect Strategy

You can configure reconnect patterns via Config\ArrayProvider or inject a custom ReconnectStrategy by implementing Reconnect\StrategyInterface.

⚙️ Statement Caching

Prepared statements are cached internally to avoid repeated preparation overhead:

To clear the statement cache (e.g. after schema changes or to free memory):

🔧 Advanced Usage

📡 ConnectionManager

The ConnectionManager class enables application-wide connection pooling and shared configuration. It’s ideal for large applications, services, or frameworks that require multiple named database instances or shared lifecycle control.

💡 ConnectionManager will automatically reuse idle connections if available.

⚙️ Configuration Providers

The Config\ArrayProvider class is a simple implementation of the ProviderInterface that lets you define connection settings in plain PHP arrays.

To use a different configuration source (like .env, JSON, or YAML), implement:

This keeps your configuration logic separate from your application logic, and makes it easy to test or extend.

🧪 Testing

Tests require a MySQL server with a testdb database. You can configure your environment using .env variables or phpunit.xml:

Run tests with:

To generate a coverage report (requires Xdebug or PCOV):

🤝 Contributing

Contributions are welcome! To get started:

1. Fork the repository
2. Create a new branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -am 'Add feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a pull request

🧭 Code of Conduct

Please be respectful and constructive in all interactions. We aim to foster a professional, welcoming environment.

🔐 Security

If you discover a security vulnerability, please report it privately via GitHub or email the maintainer. Avoid opening public issues for sensitive disclosures.

📄 License

This package is open-source software licensed under the MIT license.