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

v4.5.2(1mo ago)34.8k↓66.7%1[3 PRs](https://github.com/satwareAG/doctrine-firebird-driver/pulls)MITPHPPHP ^8.2CI passing

Since Dec 19Pushed 3w 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 2w ago

READMEChangelog (10)Dependencies (112)Versions (40)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.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](https://packagist.org/packages/doctrine/dbal#4.4.0) (4.4.x branch, current release: v4.5.1)
- [doctrine/dbal ^3.10](https://packagist.org/packages/doctrine/dbal#3.10.0) (3.10.x branch, maintenance only: v3.19.0)

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

[](#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 require 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 11, 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 v13.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

56

—

FairBetter than 97% of packages

Maintenance95

Actively maintained with recent releases

Popularity27

Limited adoption so far

Community18

Small or concentrated contributor base

Maturity71

Established project with proven stability

 Bus Factor1

Top contributor holds 67.3% 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 ~35 days

Recently: every ~0 days

Total

38

Last Release

30d ago

Major Versions

2.8.1 → 3.0.02024-10-01

v3.10.5 → v4.4.02026-04-09

v3.12.4 → v4.4.12026-04-10

v3.19.0 → v4.5.02026-07-19

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 (575 commits)")[![satwareAG-ironMike](https://avatars.githubusercontent.com/u/59868837?v=4)](https://github.com/satwareAG-ironMike "satwareAG-ironMike (242 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] (9 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

[symfony/symfony

The Symfony PHP framework

31.4k87.4M2.2k](/packages/symfony-symfony)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.8M674](/packages/shopware-core)[shopware/platform

The Shopware e-commerce core

3.4k1.5M3](/packages/shopware-platform)[laravel/framework

The Laravel Framework.

34.9k556.2M21.5k](/packages/laravel-framework)[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

762297.9k53](/packages/civicrm-civicrm-core)[perplorm/perpl

Perpl is an improved and still maintained fork of Propel2, an open-source Object-Relational Mapping (ORM) for PHP.

2414.4k](/packages/perplorm-perpl)

PHPackages © 2026

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