PHPackages                             satag/doctrine-firebird-driver - 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. satag/doctrine-firebird-driver

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

satag/doctrine-firebird-driver
==============================

Doctrine DBAL/ORM driver for Firebird SQL 3.0 and newer

v3.12.3(2mo ago)33.6k↓46.7%[1 issues](https://github.com/satwareAG/doctrine-firebird-driver/issues)MITPHPPHP ^8.2CI passing

Since Dec 19Pushed 1mo ago3 watchersCompare

[ Source](https://github.com/satwareAG/doctrine-firebird-driver)[ Packagist](https://packagist.org/packages/satag/doctrine-firebird-driver)[ RSS](/packages/satag-doctrine-firebird-driver/feed)WikiDiscussions 4.4.x Synced 1mo ago

READMEChangelog (10)Dependencies (51)Versions (23)Used By (0)

Doctrine Firebird driver
------------------------

[](#doctrine-firebird-driver)

[![codecov](https://camo.githubusercontent.com/d933617af49c34ae19b2c7be6761a305be0da9faa2fb4f0ad38e6b622d11f66b/68747470733a2f2f636f6465636f762e696f2f6769746875622f7361747761726541472f646f637472696e652d66697265626972642d6472697665722f67726170682f62616467652e7376673f746f6b656e3d4f363659563654474d31)](https://codecov.io/github/satwareAG/doctrine-firebird-driver)

[Firebird](https://firebirdsql.org/) driver for the [Doctrine DBAL](https://github.com/doctrine/dbal)

Requirements
============

[](#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.4 recommended** — primary optimization target for Amicron ERP integration)
- **php-firebird extension** v7.3.0+ (satwareAG fork with IBatch, Exception Mode, OO API, PHP 8.4 hardening)
- [doctrine/dbal ^3.10](https://packagist.org/packages/doctrine/dbal#3.10.0) (3.10.x branch)
- [doctrine/dbal ^4.4](https://packagist.org/packages/doctrine/dbal#4.4.0) (4.4.x branch)

Version Compatibility Matrix
----------------------------

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

[](#license--disclaimer)

See [LICENSE](LICENSE) file. Basically: Use this library at your own risk.

Limitations of Schema Manager
-----------------------------

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

[](#installation)

Via Composer ([`satag/doctrine-firebird-driver`](https://packagist.org/packages/satag/doctrine-firebird-driver)):

```
composer install satag/doctrine-firebird-driver

```

Via Github:

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

```

Error Handling with SQLSTATE
----------------------------

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

[](#doctrine-exception-mapping)

SQLSTATE ClassDoctrine ExceptionDescription08xxxConnectionExceptionConnection errors23xxxConstraintViolationIntegrity constraints23502NotNullConstraintViolationExceptionNOT NULL violation23503ForeignKeyConstraintViolationExceptionFK violation23505UniqueConstraintViolationExceptionUnique violation40xxxDeadlockExceptionTransaction rollback42xxxSyntaxErrorExceptionSQL syntax errors### Custom Exception Handling

[](#custom-exception-handling)

```
use Doctrine\DBAL\Exception\UniqueConstraintViolationException;

try {
    $conn->insert('users', ['email' => 'duplicate@example.com']);
} catch (UniqueConstraintViolationException $e) {
    // SQLSTATE 23505 - handle duplicate
    $sqlState = $e->getSQLState(); // Returns '23505'
}
```

Working with LIKE Expressions
-----------------------------

[](#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](docs/firebird-like-best-practices.md) for detailed strategies and examples.

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

Configuration
-------------

[](#configuration)

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

[](#recommended-using-firebirdconnection-wrapper-dbal-4x-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)

[](#php-configuration-recommended)

```
use Doctrine\DBAL\DriverManager;
use Satag\DoctrineFirebirdDriver\DBAL\FirebirdConnection;

$params = [
    'driver_class' => \Satag\DoctrineFirebirdDriver\Driver\Firebird\Driver::class,
    'host'         => 'localhost',
    'dbname'       => '/path/to/database.fdb',
    'user'         => 'SYSDBA',
    'password'     => 'masterkey',
    'charset'      => 'UTF8',

    // Use the FirebirdConnection wrapper (DBAL 4.x compatible)
    'wrapperClass' => FirebirdConnection::class,

    // Firebird-specific configuration options
    'firebird'     => [
        'like_cast_length' => 500,  // Configure LIKE CAST length (default: 255)
    ],
];

$connection = DriverManager::getConnection($params);
```

#### Symfony Configuration (YAML)

[](#symfony-configuration-yaml)

```
doctrine:
    dbal:
        default_connection: default
        connections:
            default:
                driver_class:   Satag\DoctrineFirebirdDriver\Driver\Firebird\Driver
                wrapper_class:  Satag\DoctrineFirebirdDriver\DBAL\FirebirdConnection
                host:           "%database_host%"
                port:           "%database_port%"
                dbname:         "%database_name%"
                user:           "%database_user%"
                password:       "%database_password%"
                charset:        "UTF-8"

                # Firebird-specific options (passed through wrapper)
                options:
                    firebird:
                        like_cast_length: 500  # Default: 255
```

### Configurable LIKE CAST Length

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

[](#legacy-configuration-deprecated-in-dbal-3x-removed-in-dbal-4x)

> ⚠️ **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](#recommended-using-firebirdconnection-wrapper-dbal-4x-compatible) above for forward compatibility.

#### Manual Configuration (Legacy)

[](#manual-configuration-legacy)

```
use Doctrine\DBAL\DriverManager;

$params = [
    'driver_class' => \Satag\DoctrineFirebirdDriver\Driver\Firebird\Driver::class,
    'host'         => 'localhost',
    'dbname'       => '/path/to/database.fdb',
    'user'         => 'SYSDBA',
    'password'     => 'masterkey',
    'charset'      => 'UTF8',

    // Optional: Configure LIKE CAST length (default: 255)
    'firebird'     => [
        'like_cast_length' => 500,  // Increase for longer search parameters
    ],
];

$connection = DriverManager::getConnection($params);
```

#### Symfony Configuration (YAML)

[](#symfony-configuration-yaml-1)

This driver may be used like any other Doctrine DBAL driver in [Symfony](https://symfony.com/), e.g. with [doctrine/doctrine-bundle](https://packagist.org/packages/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](https://github.com/doctrine/dbal).

Sample YAML configuration:

```
doctrine:
    dbal:
        default_connection: default
        connections:
            default:
                driver_class:   Satag\DoctrineFirebirdDriver\Driver\Firebird\Driver
                host:           "%database_host%"
                port:           "%database_port%"
                dbname:         "%database_name%"
                user:           "%database_user%"
                password:       "%database_password%"
                charset:        "UTF-8"

                # Optional: Configure Firebird-specific options
                options:
                    firebird:
                        like_cast_length: 500  # Default: 255
```

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

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

[](#symfony-configuration-doctrinebundle-service)

```

```

```
# config/services.yaml
Satag\DoctrineFirebirdDriver\Driver\Firebird\Middleware\CharsetMiddleware:
    tags:
        - { name: doctrine.middleware }
```

#### Standalone PHP Configuration

[](#standalone-php-configuration)

```
use Doctrine\DBAL\Configuration;
use Doctrine\DBAL\DriverManager;
use Satag\DoctrineFirebirdDriver\Driver\Firebird\Middleware\CharsetMiddleware;

$config = new Configuration();
$config->setMiddlewares([
    new CharsetMiddleware(), // defaults: WIN1252 → UTF-8
]);

$connection = DriverManager::getConnection([
    'driver_class' => \Satag\DoctrineFirebirdDriver\Driver\Firebird\Driver::class,
    'host'         => 'localhost',
    'dbname'       => '/path/to/database.fdb',
    'user'         => 'SYSDBA',
    'password'     => 'masterkey',
    'charset'      => 'WIN1252',
], $config);
```

#### Custom Encoding Pair

[](#custom-encoding-pair)

```
// ISO-8859-1 database, UTF-8 application
$middleware = new CharsetMiddleware(databaseEncoding: 'ISO-8859-1', phpEncoding: 'UTF-8');

// UTF-8 database (no conversion needed - use identity pair)
$middleware = new CharsetMiddleware(databaseEncoding: 'UTF-8', phpEncoding: 'UTF-8');
```

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

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

[](#quick-test-commands)

```
# Run all tests for all Firebird versions
cd tests && ./phpunit-all.sh

# Run complete quality check (PHPUnit, PHPStan, Psalm, PHPCS)
cd tests && ./docker-cqc.sh

# Run tests for Firebird 3.0 only
cd tests && ./phpunit.sh

# Run specific test suite
vendor/bin/phpunit tests/Test/Unit/
vendor/bin/phpunit tests/Test/Functional/
```

Test Coverage
-------------

[](#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 10.5, PHPStan Level 8, Psalm static analysis

Documentation
-------------

[](#documentation)

- **[TESTING.md](docs/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](docs/CONTRIBUTING.md)** - Contributor guidelines

    - Quick start for developers
    - Pull request requirements
    - Development workflow
    - Code style guidelines
    - Testing requirements

Test Requirements
-----------------

[](#test-requirements)

- **Docker & Docker Compose** - For running test environment
- **PHP 8.2+** with `ext-firebird` (php-firebird v7.3.0+)
- **Composer dependencies** - `composer install`

All tests run in Docker containers to ensure consistent environments across Firebird versions. See [TESTING.md](docs/TESTING.md) for detailed setup instructions.

Credits
=======

[](#credits)

Authors
-------

[](#authors)

- **Kasper Søfren**

    E-mail:
- **Uffe Pedersen**

Acknowledgements
----------------

[](#acknowledgements)

###

[](#httpsgithubcomdoctrinedbal)

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`](https://github.com/doctrine/dbal/blob/v2.9.3/lib/Doctrine/DBAL/Driver/PDOOracle/Driver.php) and [`\Doctrine\DBAL\Platforms\OraclePlatform`](https://github.com/doctrine/dbal/blob/v2.9.3/lib/Doctrine/DBAL/Platforms/OraclePlatform.php), and their respective parent classes.

###

[](#httpsgithubcomhelicon-osdoctrine-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 , although, this is not specifically stated.
- It is not a Composer package (not on ).

###

[](#httpsgithubcomistdkdoctrine-dbal)

A fork of  with a few improvements and fixes.

###

[](#httpsfirebirdsqlorg)

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

### AI Context-Setting Statement

[](#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
    -  supports DBAL ^3.10 (Maintenance)
    -  supports DBAL ^4.4 (Active)
- Doctrine DBAL Driver documentation: [Doctrine DBAL](https://www.doctrine-project.org/projects/doctrine-dbal/en/4.1/reference/supporting-other-databases.html)
- Reference manuals of Firebird’s implementation of the SQL relational database language for
    [Firebird 2.5](https://firebirdsql.org/file/documentation/html/en/refdocs/fblangref25/firebird-25-language-reference.html), [Firebird 3.0](https://firebirdsql.org/file/documentation/html/en/refdocs/fblangref30/firebird-30-language-reference.html)and [Firebird 4.0](https://firebirdsql.org/file/documentation/html/en/refdocs/fblangref30/firebird-30-language-reference.html)
- PHP Firebird Extension Source: [PHP Firebird extension](https://github.com/FirebirdSQL/php-firebird)
- [German Firebird Forum](https://www.firebirdforum.de/)
- 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.

###  Health Score

51

—

FairBetter than 96% of packages

Maintenance82

Actively maintained with recent releases

Popularity26

Limited adoption so far

Community17

Small or concentrated contributor base

Maturity68

Established project with proven stability

 Bus Factor1

Top contributor holds 64.5% 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 ~59 days

Recently: every ~2 days

Total

21

Last Release

56d ago

Major Versions

2.8.1 → 3.0.02024-10-01

v3.12.2 → 4.4.x-dev2026-03-18

PHP version history (3 changes)2.8.0PHP >=7.4

3.0.0PHP ^8.1

v3.10.0-RC.2PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/44b85e5ce069ccae08123600bb24204ea8fe99c8cb5cbfae108ff29c179e503d?d=identicon)[jschwind](/maintainers/jschwind)

![](https://www.gravatar.com/avatar/9fd23bbd806ea092ef8caa3276cbca0395689c9413cf7a79a300d3391adeda8e?d=identicon)[satwareAG-ironMike](/maintainers/satwareAG-ironMike)

![](https://www.gravatar.com/avatar/5f58eb576de05617c39eb83472adda4db5ef996e8ce8ad2685583cfe798e51fa?d=identicon)[jane-alesi](/maintainers/jane-alesi)

---

Top Contributors

[![jane-alesi](https://avatars.githubusercontent.com/u/193043945?v=4)](https://github.com/jane-alesi "jane-alesi (375 commits)")[![satwareAG-ironMike](https://avatars.githubusercontent.com/u/59868837?v=4)](https://github.com/satwareAG-ironMike "satwareAG-ironMike (172 commits)")[![kafoso](https://avatars.githubusercontent.com/u/3169691?v=4)](https://github.com/kafoso "kafoso (15 commits)")[![MWsatwareAG](https://avatars.githubusercontent.com/u/14194847?v=4)](https://github.com/MWsatwareAG "MWsatwareAG (10 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (5 commits)")[![DSsatwareAG](https://avatars.githubusercontent.com/u/14197761?v=4)](https://github.com/DSsatwareAG "DSsatwareAG (3 commits)")[![e-belair](https://avatars.githubusercontent.com/u/596562?v=4)](https://github.com/e-belair "e-belair (1 commits)")

---

Tags

ormdoctrinedbalsqlfirebirdinterbasedatabase driverfbirdfirebird driversql driver

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Psalm

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/satag-doctrine-firebird-driver/health.svg)

```
[![Health](https://phpackages.com/badges/satag-doctrine-firebird-driver/health.svg)](https://phpackages.com/packages/satag-doctrine-firebird-driver)
```

###  Alternatives

[illuminate/database

The Illuminate Database package.

2.8k52.4M9.4k](/packages/illuminate-database)[scienta/doctrine-json-functions

A set of extensions to Doctrine that add support for json query functions.

58723.9M36](/packages/scienta-doctrine-json-functions)[vlucas/spot2

Simple DataMapper built on top of Doctrine DBAL

605392.8k7](/packages/vlucas-spot2)[jsor/doctrine-postgis

Spatial and Geographic Data with PostGIS and Doctrine.

2191.6M1](/packages/jsor-doctrine-postgis)[cycle/database

DBAL, schema introspection, migration and pagination

64690.9k31](/packages/cycle-database)[kdyby/doctrine

Doctrine integration into Nette Framework

1091.0M86](/packages/kdyby-doctrine)

PHPackages © 2026

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