Download the PHP package satag/doctrine-firebird-driver without Composer

Doctrine Firebird driver

Firebird driver for the Doctrine DBAL

Requirements

To utilize this library in your application code, the following is required:

• Firebird Server: 3.0+ (minimum; 4.0 and 5.0 also supported - 2.5 dropped in php-firebird v7.2.0)
• PHP: >= 8.2 (8.5 recommended - primary optimization target for Amicron ERP integration)
• php-firebird extension v13.0+ (satwareAG fork with M3 opaque-object API, IBatch, Exception Mode, OO API, PHP 8.4/8.5 hardening, fbird_escape_literal())
• doctrine/dbal ^4.4 (4.4.x branch, current release: v4.5.1)
• doctrine/dbal ^3.10 (3.10.x branch, maintenance only: v3.19.0)

Version Compatibility Matrix

| Feature | FB 3.0 | FB 4.0 | FB 5.0 |

|---------|--------|--------|--------| | Basic DBAL (queries, transactions) | ✅ | ✅ | ✅ | | Schema introspection | ✅ | ✅ | ✅ | | Named parameters | ✅ | ✅ | ✅ | | BLOB support | ✅ | ✅ | ✅ | | Exception Mode (Firebird\Exception) | ✅ | ✅ | ✅ | | SQLSTATE Error Mapping | ✅ | ✅ | ✅ | | Standard Pagination (OFFSET/FETCH) | ✅ | ✅ | ✅ | | fbird_execute_auto() auto-commit | ✅ | ✅ | ✅ | | fbird_connection_info() / DbInfo | ✅ | ✅ | ✅ | | Savepoints (nested transactions) | ✅ | ✅ | ✅ | | IBatch API (bulk INSERT 10-12×) | ❌ | ✅ | ✅ | | RETURNING multi-row | ❌ | ✅ | ✅ | | SCROLL cursors | ❌ | ✅ | ✅ | | DECFLOAT type | ❌ | ✅ | ✅ | | TIME ZONE / TIMESTAMP TZ | ❌ | ✅ | ✅ |

Breaking change (php-firebird v7.2.0+): Firebird 2.5 support dropped. Minimum server version is 3.0.

Windows Support: Starting with v7.3.0, pre-built Windows DLLs are available for PHP 8.2, 8.3, 8.4, and 8.5 (NTS and TS).

Note: Firebird 3.0 is the primary production target (Amicron ERP). Features marked ❌ for FB3 are either absent on the server or require Firebird 4.0+. Feature detection is automatic — no manual configuration is needed.

License & Disclaimer

See LICENSE file. Basically: Use this library at your own risk.

Limitations of Schema Manager

This library does not fully support generation through the Schema Manager, i.e.:

1. Generation of database tables, views, etc. from entities.
2. Generation of entities from database tables, views, etc.

Reasons for not investing time in schema generation include that Firebird does not allow renaming of tables, which in turn makes automated schema updates annoying and over-complicated. Better results are probably achieved by writing manual migrations.

Installation

Via Composer (satag/doctrine-firebird-driver):

composer require satag/doctrine-firebird-driver

Via Github:

git clone https://github.com/satwareAG/doctrine-firebird-driver.git

Error Handling with SQLSTATE

With php-firebird v7.0.0+, the driver provides standardized SQLSTATE error codes for better error classification and handling. When Exception Mode is enabled (default), the driver maps these to specific Doctrine exceptions.

Doctrine Exception Mapping

Custom Exception Handling

Working with LIKE Expressions

Firebird has a known issue where LIKE parameters longer than a column’s VARCHAR length can cause silent query failures (zero rows returned instead of an error). This driver automatically wraps the left operand of LIKE/NOT LIKE with CAST(column AS VARCHAR(255)) to prevent this behavior.

Performance note: Casting disables index usage for that predicate and can trigger full table scans on large tables. To mitigate:

• Filter by indexed columns first in the WHERE clause.
• Validate parameter length at the application layer when appropriate.
• See our Best Practices Guide for detailed strategies and examples.

Validated across: Firebird 3.0, 4.0, 5.0 (24/24 tests passing)

Configuration

Recommended: Using FirebirdConnection Wrapper (DBAL 4.x Compatible)

For forward compatibility with Doctrine DBAL 4.x, we recommend using the FirebirdConnection wrapper class. This approach properly handles Firebird-specific configuration options and is the recommended way to configure Firebird-specific settings.

Why use FirebirdConnection?

• Forward-compatible with DBAL 4.x (which removes VersionAwarePlatformDriver)
• Cleanly separates Firebird configuration from driver logic
• Proper access to both connection parameters and platform instance

PHP Configuration (Recommended)

Symfony Configuration (YAML)

Configurable LIKE CAST Length

The driver wraps LIKE column operands in CAST(column AS VARCHAR(length)) to prevent silent query failures when parameters exceed column lengths. The CAST length is configurable:

Default: 255 (backward compatible)
Range: 1 to 8191 (Firebird VARCHAR limit)
Parameter: firebird.like_cast_length

Legacy Configuration (Deprecated in DBAL 3.x, Removed in DBAL 4.x)

⚠️ Deprecation Warning: The following configuration approach works in DBAL 3.x but relies on the deprecated VersionAwarePlatformDriver interface, which is removed in DBAL 4.x. Use the FirebirdConnection wrapper above for forward compatibility.

Manual Configuration (Legacy)

Symfony Configuration (YAML)

This driver may be used like any other Doctrine DBAL driver in Symfony, e.g. with doctrine/doctrine-bundle. However, the driver_class option must be specified instead of simply driver. This is due to the driver not being part of the core Doctrine DBAL library.

Sample YAML configuration:

When to adjust like_cast_length:

• 100-255: Small text fields, optimized performance
• 500-1000: Medium text fields, typical applications
• 1000-8191: Large text fields, full-text search (slower)

Invalid configurations throw InvalidConfigurationException:

• Type mismatch (non-integer values)
• Out of range (<1 or >8191)

CharsetMiddleware - Transparent Charset Conversion

Many Firebird databases use a non-UTF-8 wire charset (e.g. ISO8859_1 / WIN1252). The CharsetMiddleware converts string values transparently between your PHP application encoding and the Firebird wire encoding at the DBAL driver level - no manual iconv/mb_convert_encoding calls needed in application code.

Defaults: databaseEncoding: 'Windows-1252' and phpEncoding: 'UTF-8' covers the most common case (Amicron ERP and other WIN1252 Firebird databases).

Symfony Configuration (DoctrineBundle service)

Standalone PHP Configuration

Custom Encoding Pair

How it works:

• bindValue() / execute params: PHP encoding → database encoding before sending to Firebird.
• fetch*() results: database encoding → PHP encoding after receiving from Firebird.
• BLOB Transparency: PHP resource streams are automatically extracted and transcoded.
• LARGE_OBJECT support: Parameters bound with ParameterType::LARGE_OBJECT are transcoded.
• Non-string values (int, float, null, bool, objects) pass through unchanged.

Requires: ext-mbstring (declared in composer.json)

Testing

The project includes comprehensive test coverage across Firebird 3.0, 4.0, and 5.0 with unit, functional, and integration tests.

Quick Test Commands

Test Coverage

• 1255+ tests (unit, functional, integration)
• 100% pass rate across all Firebird versions (3.0, 4.0, 5.0)
• Windows CI — Fully stabilized integration tests on GitHub Actions using dedicated permissive storage (C:\firebird_tests) to bypass SYSTEM account I/O restrictions.
• CI/CD Audit — Regular audits ensure parity between local (docker-cqc.sh, act) and remote GitHub Actions environments.
• PHPUnit 11, PHPStan Level 8, Psalm static analysis

Documentation

• TESTING.md - Comprehensive testing guide

  • Project test structure
  • PHPUnit configuration files
  • Writing new tests
  • Namespace conventions
  • Troubleshooting guide
  • Multi-version testing
  • CI/CD integration
• CONTRIBUTING.md - Contributor guidelines
  • Quick start for developers
  • Pull request requirements
  • Development workflow
  • Code style guidelines
  • Testing requirements

Test Requirements

• Docker & Docker Compose - For running test environment
• PHP 8.2+ with ext-firebird (php-firebird v13.0+)
• Composer dependencies - composer install

All tests run in Docker containers to ensure consistent environments across Firebird versions. See TESTING.md for detailed setup instructions.

Credits

Authors

• Kasper Søfren
  https://github.com/kafoso
  E-mail: [email protected]
• Uffe Pedersen
  https://github.com/upmedia

Acknowledgements

https://github.com/doctrine/dbal

Fundamental Doctrine DBAL implementation. The driver and platform logic in this library is based on other implementations in the core library, largely \Doctrine\DBAL\Driver\PDOOracle\Driver and \Doctrine\DBAL\Platforms\OraclePlatform, and their respective parent classes.

https://github.com/helicon-os/doctrine-dbal

Whilst a great inspiration for this library - and we very much appreciate the work done by the authors - the library has a few flaws and limitations regarding the Interbase Firebird driver logic:

• It contains bugs. E.g. incorrect/insufficient handling of nested transactions and save points.
• It is lacking with respect to test coverage.
• It appears to no longer be maintained. Possibly entirely discontinued.
• It is intermingled with the core Doctrine DBAL code, making version management and code adaptation unnecessarily complicated; a nightmare, really. It is forked from https://github.com/doctrine/dbal, although, this is not specifically stated.
• It is not a Composer package (not on https://packagist.org).

https://github.com/ISTDK/doctrine-dbal

A fork of https://github.com/helicon-os/doctrine-dbal with a few improvements and fixes.

https://firebirdsql.org/

The main resource for Firebird documentation, syntax, downloads, etc.

AI Context-Setting Statement

As an AI specialized in coding, your task is to support me, Michael Wegener, to improve the PHP Doctrine DBAL driver for the Firebird SQL Server for which I am the current maintainer. The Driver is not based on Firebird PDO, it is based on the PHP Firebird Extension (fbird* functions; ibase* aliases removed in php-firebird v7.2.0). You can reference the following resources for guidance:

• satag/doctrine-firebird-driver Source Code Branches
  • https://github.com/satwareAG/doctrine-firebird-driver/tree/3.10.x supports DBAL ^3.10 (Maintenance)
  • https://github.com/satwareAG/doctrine-firebird-driver/tree/4.4.x supports DBAL ^4.4 (Active)
• Doctrine DBAL Driver documentation: Doctrine DBAL
• Reference manuals of Firebird’s implementation of the SQL relational database language for
  Firebird 2.5, Firebird 3.0 and Firebird 4.0
• PHP Firebird Extension Source: PHP Firebird extension
• German Firebird Forum
• You can download all given resources for reference.

The PHP Driver is implemented for PHP 8.2+ and should be covered with PHP Unit and Integration Tests against all supported Firebird Server Versions (3.0+). Have an eye on modern development principles, performance and security.