Download the PHP package satwareag/php-firebird without Composer

PHP Firebird Extension (Modernized)

A high-performance PHP extension providing native connectivity to Firebird databases. This modernized version targets PHP 8.2+ with C++17 standards and comprehensive development tooling.

⚠️ Breaking Changes in v7.0: This version uses fbird_* function names (not ibase_*) and builds as firebird.so (not interbase.so). See the Migration Guide for upgrade instructions.

Features

• Native Performance: Direct fbclient library integration
• Full Firebird Support: Connects to Firebird 3.0, 4.0, 5.0+ servers (tested against full 12-target PHP/Firebird matrix)
• Modern C++ OO API: Uses Firebird 3.0+ Object-Oriented API with RAII wrappers — zero legacy isc_* calls
• Modern PHP: Optimized for PHP 8.2+ with typed properties and attributes
• *Layer 1 — `fbird_` procedural API**: Full-featured function-based interface for Firebird-specific features
• Layer 2 — Firebird\* OOP classes: Native C-registered PHP classes (Exception, DatabaseException, TransactionException, Connection, Transaction, Statement, ResultSet, Blob, Service, Event, BatchHandle, DecFloat) with Firebird-specific features
• Layer 3 — pdo_fbird PDO driver: Separate pdo_fbird.so extension with fbird: DSN prefix, compatible with PDO without colliding with PHP's bundled pdo_firebird. Load after firebird.so.
• Exception Mode API: PDO-style exception handling with runtime switchable error modes (SILENT/THROW)
• Memory Safety: Built with AddressSanitizer and comprehensive static analysis
• Cross-Platform: Linux, Windows, macOS support
• Clean API: fbird_* function prefix (no legacy InterBase naming)
• LTO Optimized: Link-Time Optimization enabled by default for GCC 8+ (auto-disabled for PHP < 8.3 and sanitizers)

API Layers

This extension provides three complementary API layers:

When to use pdo_fbird (Layer 3):

• Building database-agnostic applications that need PDO compatibility
• Migrating from PDO_Firebird without changing application code structure
• Simple CRUD operations via PDO interface

When to use Firebird\* classes (Layer 2):

• OOP-style code with Firebird-specific features (events, service API)
• Modern PHP applications preferring class-based APIs

*When to use `fbird_` functions (Layer 1):**

• Firebird array field support required
• Advanced transaction control (savepoints, table locking, TPB)
• Performance-critical applications
• Full service API (backup, restore, user management)

Requirements

System Requirements

• PHP: 8.2+ with development headers
• C++ Compiler: GCC 7+ or Clang 5+ (C++17 support)
• Firebird: 3.0+ client libraries (fbclient) and headers
• Build Tools: autotools, make, pkg-config

⚠️ Firebird 3.0+ Client Library Required: This extension requires the Firebird 3.0+ client library (fbclient) for building, as it uses the modern OO API (FB_API_VER >= 30). Supported server versions: 3.0, 4.0, 5.0+.

Supported Platforms

• Linux x86_64 and ARM64/aarch64 (Ubuntu 20.04+, Debian 11+, Rocky/AlmaLinux 8+, openSUSE 15.3+)
• Linux musl/Alpine (Alpine 3.18+, x86_64)
• Windows 10/11 x64 (Visual Studio 2019+)
• macOS arm64 (Apple Silicon, macOS 11+)

Note: glibc 2.28+ required for glibc precompiled binaries; musl 1.2+ for Alpine binaries. PHP 8.2+ is required.

Precompiled Binary Matrix (v12.0.0+)

Download from the Releases Page.

Quick Start

Docker Development (Recommended)

Native Installation

Linux (Ubuntu/Debian)

Linux (openSUSE)

Linux / macOS (Pre-compiled Bundles)

Pre-compiled bundles include firebird.so with bundled Firebird client libraries ($ORIGIN/lib/ RPATH).

1. Go to the Releases Page.
2. Download the bundle matching your platform, PHP version, and thread safety (NTS/ZTS).
3. Extract: tar -xzf php-firebird-*.tar.gz
4. Copy firebird.so and lib/ to your PHP extension directory.
5. Add extension=firebird.so to your php.ini.

Windows (Pre-compiled DLLs)

Pre-compiled Windows DLLs for PHP 8.2-8.5 (x64, NTS/TS).

1. Go to the Releases Page.
2. Download the .zip matching your PHP version and thread safety.
3. See the Windows Installation Guide for detailed instructions.

Windows (Manual Build)

macOS (Homebrew)

Usage Example

Exception Handling

The extension provides PDO-style exception handling with runtime switchable error modes:

Exception Mode API:

• fbird_set_exception_mode(int $mode) - Set error handling mode (SILENT or THROW)
• fbird_get_exception_mode() - Get current error handling mode
• FBIRD_EXCEPTION_MODE_SILENT - Traditional PHP warnings (default, backward compatible)
• FBIRD_EXCEPTION_MODE_THROW - Throw Firebird\Exception on errors (PDO-style)

Common SQLSTATE Codes:

• 23000 - Integrity constraint violation
• 42000 - Syntax error or access rule violation
• HY000 - General error

Doctrine DBAL Integration: Exception mode is required for Doctrine DBAL 4.x compatibility. Enable THROW mode at application bootstrap:

Transactions Example

Advanced Transactions with TPB (Transaction Parameter Block)

The extension provides comprehensive transaction control via the Transaction Parameter Block (TPB):

Transaction Flags (combinable with |):

Table Reservation Flags (for tables array option):

Prepared Statements Example

BLOB Handling Example

Configuration

Runtime Configuration

⚠️ Breaking Change (v7.0): INI settings have been renamed from ibase.* to fbird.*. Update your php.ini configuration accordingly. ⚠️ Breaking Change (v12.0): pdo_fbird is now a separate extension. Add extension=pdo_fbird.so to your php.ini (after firebird.so) to use the fbird: PDO DSN.

Supported Input Date/Time Formats

When binding date/time parameters, the extension auto-detects the following formats:

Timestamp Formats: Combine any date format with any time format, separated by space or T:

• 2025-12-17 14:30:00
• 2025-12-17T14:30:00.1234+01:00
• 17.12.2025 14:30:00 America/New_York

Timezone Support (Firebird 4.0+):

• Offset format: +HH:MM, -HH:MM, +HHMM, -HHMM
• Named zones: IANA timezone names (e.g., America/New_York, Europe/Berlin)
• UTC shorthand: Z

Environment Variables

Migration Guide

Migrating from ext/interbase or Legacy php-firebird

This version uses the modern fbird_* function prefix instead of ibase_*. Here's how to migrate:

Function Name Changes

Quick Migration Script

For simple projects, you can use search-and-replace:

Extension Loading Changes

Build Flag Changes

Resource Type Changes

Resource types have also been renamed for clarity:

Why the Change?

This extension was originally forked from PHP's ext/interbase. The rename to fbird_* functions:

1. Reflects modern reality: InterBase is essentially defunct; Firebird is the active successor
2. Clear differentiation: Makes it obvious this is a new, maintained driver
3. Clean break: Encourages users to review and test their code during migration
4. Future-proof: No confusion with legacy or potentially conflicting code

Testing

Running Tests

make test only loads firebird.so (the main extension). To test PDO functionality, use run-tests.php with explicit extension loading:

The CI runs 389 .phpt tests across 12 containers (PHP 8.2-8.5 x FB 3.0/4.0/5.0).

Test Environment Setup

Troubleshooting

Common Build Issues

Missing fbclient library:

PHP version conflicts:

Windows Visual Studio version:

• Use Visual Studio 2019+ (vs16) for PHP 8.2-8.3
• Use Visual Studio 2022 (vs17) for PHP 8.4+
• Ensure Windows SDK 10.0.20348.0+ is installed
• For compatibility, use same compiler as your PHP build

Connection Behavior

Connection Reuse (Default Behavior):

By design, fbird_connect() reuses existing connections when called with identical parameters. This matches PostgreSQL's pg_connect() behavior and provides efficiency benefits for typical use cases:

When You Need Separate Connections:

If you need independent connections (e.g., for parallel transactions, different isolation levels, or connection-specific state), use one of these approaches:

Force New Connection (v7.0+):

Use the FBIRD_CONNECT_FORCE_NEW flag (value: 2) to bypass connection reuse and create a new database connection:

This flag mirrors PostgreSQL's PGSQL_CONNECT_FORCE_NEW behavior and is useful for:

• Parallel operations within the same request
• Testing scenarios requiring isolated connections
• Connection pool implementations

Performance Optimization

Connection Pooling:

Prepared Statements:

Development

Contributing

See CONTRIBUTING.md for detailed development guidelines including:

• Modern C++17 development standards
• Static analysis tool integration
• Cross-platform testing procedures
• Docker development environment

Development Tools

• Static Analysis: clang-tidy, Cppcheck
• Memory Safety: AddressSanitizer, ThreadSanitizer (ZTS), Valgrind
• Debugging: GDB/LLDB with PHP symbols
• IDE Support: CLion, VS Code, Visual Studio

Architecture

• Language: C (main extension) + C++ (utilities) with C++17 standard
• API: Zend Extension API with modern PHP 8.2+ features
• Thread Safety: Support for both ZTS and NTS builds
• Memory Model: RAII principles with automatic resource cleanup

IDE and Static Analysis Support

For IDE autocompletion and static analysis tools (PHPStan, Psalm), install the stubs package:

This provides:

• IDE Autocompletion: Full function signatures and parameter hints for PhpStorm, VSCode (Intelephense), etc.
• PHPStan/Psalm Support: Type stubs for static analysis of code using fbird_* functions
• Inline Documentation: PHPDoc comments describing each function and constant

PHPStan Configuration

The stubs are automatically loaded via Composer. For explicit configuration in phpstan.neon:

Psalm Configuration

Add to your psalm.xml:

Function Reference

Connection Functions

• fbird_connect() - Open a connection to a database
• fbird_pconnect() - Open a persistent connection
• fbird_close() - Close a database connection

Query Functions

• fbird_query() - Execute a query (link or transaction as first arg)
• fbird_query_params_tx($link, $trans, $sql, ?$params) - Execute with explicit link + transaction + params (Doctrine DBAL integration)
• fbird_prepare() - Prepare a query for later execution
• fbird_execute() - Execute a prepared query
• fbird_execute_statement() - Execute a prepared statement resource
• fbird_execute_query() - Execute SQL string with optional parameters
• fbird_execute_auto() - Auto-commit execution helper
• fbird_free_query() - Free memory allocated by a prepared query
• fbird_free_result() - Free a result set

Fetch Functions

• fbird_fetch_row() - Fetch a row as enumerated array
• fbird_fetch_assoc() - Fetch a row as associative array
• fbird_fetch_object() - Fetch a row as object

Transaction Functions

• fbird_trans() - Begin a transaction (flag-first API: fbird_trans(FLAGS, $db))
• fbird_trans_start() - Begin a transaction with array options (full TPB control)
• fbird_commit() - Commit a transaction
• fbird_commit_ret() - Commit and retain transaction context
• fbird_rollback() - Roll back a transaction
• fbird_rollback_ret() - Rollback and retain transaction context
• fbird_trans_info() - Return transaction information (ID, state, isolation)

Savepoint Functions

• fbird_savepoint() - Create a named savepoint
• fbird_rollback_savepoint() - Rollback to a named savepoint
• fbird_release_savepoint() - Release a named savepoint

Transaction Constants

• Access Modes: FBIRD_READ, FBIRD_WRITE
• Isolation Levels: FBIRD_CONCURRENCY, FBIRD_COMMITTED, FBIRD_CONSISTENCY
• Record Versioning: FBIRD_REC_VERSION, FBIRD_REC_NO_VERSION
• Lock Resolution: FBIRD_WAIT, FBIRD_NOWAIT, FBIRD_LOCK_TIMEOUT
• Table Reservation: FBIRD_LOCK_SHARED, FBIRD_LOCK_PROTECTED, FBIRD_LOCK_EXCLUSIVE, FBIRD_LOCK_READ, FBIRD_LOCK_WRITE
• Firebird 4.0+: FBIRD_READ_CONSISTENCY

BLOB Functions

• fbird_blob_create() - Create blob for adding data
• fbird_blob_open() - Open blob for retrieving data
• fbird_blob_add() - Add data to blob
• fbird_blob_get() - Get data from blob
• fbird_blob_close() - Close blob
• fbird_blob_cancel() - Cancel blob
• fbird_blob_info() - Return blob information
• fbird_blob_echo() - Output blob contents
• fbird_blob_import() - Create blob from file

Information Functions

• fbird_errmsg() - Return error message
• fbird_errcode() - Return error code
• fbird_affected_rows() - Return affected rows
• fbird_num_fields() - Get number of fields
• fbird_num_params() - Get number of parameters
• fbird_field_info() - Get field information
• fbird_param_info() - Get parameter information
• fbird_name_result() - Assign name to result set

Database Administration

• fbird_drop_db() - Drop a database

Service Functions

• fbird_service_attach() - Connect to service manager
• fbird_service_detach() - Disconnect from service manager
• fbird_backup() - Initiate backup task
• fbird_restore() - Initiate restore task
• fbird_maintain_db() - Execute maintenance command
• fbird_db_info() - Get database information
• fbird_server_info() - Get server information

User Management

• fbird_add_user() - Add a user
• fbird_modify_user() - Modify user information
• fbird_delete_user() - Delete a user

Event Functions

• fbird_set_event_handler() - Register event handler (returns Firebird\Event)
• fbird_free_event_handler() - Free event handler
• fbird_wait_event() - Wait for event
• fbird_poll_event() - Poll for events with optional timeout

OOP Event API (v12.0+):

Batch Functions (Firebird 4.0+)

• fbird_batch_create() - Create batch from prepared statement for bulk INSERT
• fbird_batch_add() - Add row with automatic type conversion
• fbird_batch_add_blob() - Create inline BLOB, returns "HHHHHHHH:LLLL" ID
• fbird_batch_register_blob() - Register existing BLOB for batch use
• fbird_batch_get_blob_alignment() - Get inline BLOB alignment requirement in bytes
• fbird_batch_append_blob_data() - Append data chunk to in-progress batch BLOB
• fbird_batch_add_blob_stream() - Add BLOB data via IBatch addBlobStream protocol
• fbird_batch_set_default_bpb() - Set default BLOB Property Block for all batch BLOBs
• fbird_batch_execute() - Execute batch (returns total_processed, success_count, error_count)
• fbird_batch_cancel() - Cancel without executing

PHP Event Polling Wrappers (src/Firebird/)

For advanced timeout and non-blocking event handling, PHP wrapper classes are provided:

See docs/oop-api.md for the Firebird\Event class reference.

Version Compatibility

Current Version: 13.2.6 (Stable Release)

Supported PHP Versions:

• PHP 8.2 (fully supported, minimum)
• PHP 8.3 (fully supported)
• PHP 8.4 (fully supported)
• PHP 8.5 (fully supported)

ℹ️ PHP 8.1: PHP 8.1 reached end-of-life on November 25, 2025 and is no longer supported as of v7.2.0. Please upgrade to PHP 8.2 or newer.

Firebird Client Library (for building):

• Firebird 3.0+ client library required (uses OO API)
• FB 5.0 client recommended (connects to all server versions)

ℹ️ Firebird 2.5 Server: Firebird 2.5 reached EOL in September 2020 and is no longer supported as of v7.2.0. Please migrate to Firebird 3.0+.

Precompiled Binaries (v12.0.0+)

Starting with v12.0.0, we provide precompiled bundles across Linux (glibc + musl), macOS (arm64), and Windows. Both firebird.so and pdo_fbird.so are included:

Package Compatibility:

• glibc 2.28+ required (Ubuntu 18.10+, Debian 11+, RHEL 8+)
• PHP 8.2+ required - use third-party repos if your distribution has an older default
• No system Firebird installation needed - client libraries bundled via $ORIGIN rpath
• Connects to any Firebird server (3.0-5.0) using bundled FB 5.x client

Installing PHP 8.2+ on Older Distributions:

If your distribution ships with PHP < 8.2, use these third-party repositories:

After installing PHP 8.2+, install the precompiled extension bundle matching your PHP version.

Dropped Support:

• ❌ PHP 7.x (legacy, security issues)
• ❌ PHP 8.0 (legacy, no longer maintained)
• ❌ PHP 8.1 (EOL Nov 2025, dropped in v7.2.0)
• ❌ Firebird 2.5 client library (requires OO API from FB 3.0+ client)
• ❌ ibase_* function aliases (use fbird_* instead)
• ❌ interbase.so extension name (use firebird.so)
• ❌ Integrated pdo_fbird in firebird.so (v12.0: load pdo_fbird.so separately)
• ❌ IB/ib_/ibase internal naming (v12.0: all renamed to FB/fb_/fbird)

Security

⚠️ SQL INJECTION WARNING: Never concatenate user input directly into SQL queries. Always use parameterized queries.

SQL Injection Prevention

✅ SAFE - Always use parameterized queries:

❌ UNSAFE - Never do this:

Escaping Functions

For cases where parameterized queries cannot be used (dynamic SQL generation), use fbird_escape_string():

Note: fbird_escape_string() is a secondary defense. Parameterized queries are always preferred.

Security Features

• Parameterized Queries: Primary defense against SQL injection
• Input Validation: Comprehensive parameter checking
• Memory Safety: AddressSanitizer integration for development
• Resource Management: Automatic cleanup prevents leaks
• String Escaping: fbird_escape_string() for dynamic SQL edge cases

For comprehensive security guidance, see docs/SECURITY.md.

Reporting Security Issues

For security-related issues, please email the maintainers directly rather than creating public issues.

License

This extension is licensed under the PHP License v3.01. See LICENSE for details.

Links

• Source Repository: https://github.com/satwareAG/php-firebird
• Firebird Documentation: https://firebirdsql.org/en/documentation/
• PHP Extensions Guide: https://www.php.net/manual/en/internals2.php
• Issue Tracker: https://github.com/satwareAG/php-firebird/issues