Skip to content

v2.6.0

Choose a tag to compare

View all tags
@tommyknocker tommyknocker released this 23 Oct 03:32
· 436 commits to master since this release
v2.6.0
000d5cf

🚀 Release v2.6.0: Comprehensive Exception Handling System

Release Date: October 23, 2025
Type: Major Release (Breaking Changes)

🎯 Overview

This major release introduces a comprehensive exception handling system that replaces generic PDOException with specialized exception types, providing better error handling capabilities and improved debugging experience.

⚠️ Breaking Changes

Exception Handling System

  • loadCsv() and loadXml() now throw specialized exceptions instead of returning false
  • All database operations now throw custom DatabaseException hierarchy instead of PDOException

Migration Guide

// Before (v2.5.x)
$result = $db->find()->table('users')->loadCsv('/path/file.csv');
if (!$result) {
    // Handle error
}

// After (v2.6.0)
try {
    $db->find()->table('users')->loadCsv('/path/file.csv');
} catch (DatabaseException $e) {
    // Handle specific exception type
}

✨ New Features

🎯 Comprehensive Exception Hierarchy

  • DatabaseException - Base exception class extending PDOException
  • ConnectionException - Connection-related errors (retryable)
  • QueryException - Query execution errors
  • ConstraintViolationException - Constraint violations with detailed context
  • TransactionException - Transaction errors (deadlocks, etc.)
  • AuthenticationException - Authentication failures
  • TimeoutException - Query/connection timeouts
  • ResourceException - Resource exhaustion errors

🏭 ExceptionFactory

  • Automatic exception type detection based on error codes and messages
  • Cross-dialect support for MySQL, PostgreSQL, and SQLite
  • Enhanced error context with driver, query, and retryable status

📊 Enhanced Error Context

catch (ConstraintViolationException $e) {
    echo "Constraint: " . $e->getConstraintName();
    echo "Table: " . $e->getTableName();
    echo "Column: " . $e->getColumnName();
    echo "Retryable: " . ($e->isRetryable() ? 'Yes' : 'No');
}

🔧 Improved Error Codes

  • DbError class with standardized error codes for all dialects
  • Helper methods for retryable error detection
  • Human-readable descriptions for error codes

🛠️ Technical Improvements

📝 Documentation & Examples

  • Comprehensive error handling examples in examples/09-exception-handling/
  • Enhanced README examples with error handling demonstrations
  • Migration guide for breaking changes
  • Exception handling best practices

🧪 Testing & Quality

  • 429 tests passing across all dialects
  • 24 examples working on MySQL, PostgreSQL, and SQLite
  • PHPStan level 8 compliance with PHPDoc annotations
  • test-examples script integrated into composer check

🔄 Connection Retry System

  • Retry mechanism with exponential backoff
  • Comprehensive logging with Monolog integration
  • Configurable retry policies for different error types

📈 Statistics

  • 18 commits in this release
  • 429 tests passing
  • 24 examples working across all dialects
  • PHPStan level 8 compliance
  • Zero external dependencies maintained

🔗 Links

Installation:

composer require tommyknocker/pdo-database-class:^2.6.0

Upgrade from v2.5.x:
Please review the breaking changes section and update your error handling code accordingly.

Assets 2
Loading