README

Propel2 is an open-source Object-Relational Mapping (ORM) for PHP. It provides Active Record-style persistence and a fluent query builder, generating typed PHP model classes from an XML schema.

Requirements

PHP 8.4+, with declare(strict_types=1) in every source file
PDO with drivers for your database of choice
Symfony 7.2+ components and Composer for dependency management

Compatibility Matrix

Propel	PHP	MySQL	MariaDB	PostgreSQL	Symfony
2.x (LTS, security only)	8.3	5.7+	10.4+	12+	7.0+
3.0	8.3	8.0+	10.5+	14+	7.2+
4.0 (this branch)	8.4	8.0+	10.5+	14+	7.2+

Supported Databases

MySQL 8.0+ / MariaDB 10.5+
PostgreSQL 14+
SQLite (kept for tests and small projects; frozen at its existing feature surface)

Oracle and SQL Server (mssql/sqlsrv) are no longer supported. See docs/MIGRATION-FROM-PRE-AI.md if you are upgrading from a Propel project that used them.

Symfony Components (^7.2)

Propel uses the following Symfony Components:

Propel relies on Composer to manage dependencies.

Installation

Read the Propel documentation.

What's new in 4.0

Propel 4.0 is a ground-up modernization targeting PHP 8.4. The public Active Record / query API (the "Tier 1" surface) stays frozen and additive — existing find(), filterBy*(), setX() code keeps working — while the internals, generated code, and tooling were rewritten. The headline changes:

PHP 8.4 baseline, strict types everywhere

Every source file declares strict_types=1 and generated model classes are fully typed: typed column properties, : self setters, typed-nullable foreign-key getters, and : static query factories. ENUM columns generate backed PHP enums, and __serialize/__unserialize replace the old __sleep/__wakeup pair.

Asymmetric property visibility on generated entities

Generated typed column properties moved from protected to public protected(set). Reads are free from anywhere; writes are restricted to the entity class hierarchy, so external direct writes now fail fast instead of silently no-op'ing on a protected property:

// 4.0 generated base class:
abstract class Author
{
    public protected(set) ?int $id = null;
    public protected(set) ?string $firstName = null;
}

echo $author->id;        // reads work everywhere
$author->setFirstName(); // writes go through setters

Connection decorator architecture

The legacy mixed-responsibility ConnectionWrapper was decomposed into a stack of single-responsibility decorators under Propel\Runtime\Connection\Internal\*: TransactionalConnection (nested-transaction accounting), LoggingConnection (PSR-3 logging without per-query debug_backtrace), CachingConnection (a bounded-LRU prepared-statement cache), and the optional ProfilingConnection and ReplicaRoutingConnection. ConnectionFactory is the single source of truth for the canonical chain order. See docs/CONNECTION-DECORATORS.md.

Primary / replica routing

Master/slave terminology and config are gone. Connection management is now ConnectionManagerPrimaryReplica, configured with primary: / replicas: keys, plus additive query hints Criteria::forcePrimary() and Criteria::allowReplica() for per-query routing control with session-consistency and primary-fallback awareness.

Streaming and lazy hydration

ModelCriteria::findStream() returns a Generator that yields one hydrated object per row as the database cursor walks, keeping memory roughly O(1) in row count instead of materializing the whole collection:

foreach ($query->findStream() as $book) {
    // one Book at a time; the full result set is never held in memory
}

Opt-in lazy relation objects (<table useLazyObjects="true">) defer per-relation collection construction using PHP 8.4 lazy ghosts, materializing on first read.

Modern enums for the query builder

Comparison, JoinType, SortOrder, and LogicalOperator backed enums live under Propel\Runtime\ActiveQuery\Operator\* alongside (never replacing) the frozen Criteria::* constants. Criteria::customCondition() provides a parameterized successor to raw Criteria::CUSTOM SQL injection.

Observability SPI

A TelemetryInterface SPI ships with a no-op default plus optional OpenTelemetry and Prometheus adapters (installed via Composer suggest), and a CompositeTelemetry to fan out to several at once. The connection decorators emit query spans, cache hit/miss counters, transaction-depth, hydration duration, and replica-routing metrics through it. See docs/TELEMETRY.md.

Tooling and cleanup

Console commands use Symfony's #[AsCommand] attribute, the migration tracking table was redesigned with migration_name / batch / checksum columns and SHA-256 drift detection, and #[\Override] is applied across the codebase. Legacy cruft was removed: DebugPDO/PropelPDO, ConnectionManagerMasterSlave, the NestedSet behavior, MyISAM plumbing, the XSLT pipeline, and the Validate / QueryCache behaviors.

Upgrading

A Rector rule set (in the rector/ package) automates most call-site rewrites — PDO wrapper replacements, master/slave config and class renames, and others. See docs/UPGRADE-4.0.md for the full migration guide, and docs/UPGRADE-3.0.md / docs/MIGRATION-FROM-PRE-AI.md when coming from older versions.

Development

Running Tests

# Run all tests (requires database setup)
composer test

# Run database-agnostic tests only (no database required)
composer test:agnostic

# Run tests for a specific database
composer test:mysql
composer test:pgsql

Set up the test database before running database-specific tests:

tests/bin/setup.sqlite.sh   # SQLite
tests/bin/setup.mysql.sh    # MySQL (requires DB_USER, DB_PW env vars)
tests/bin/setup.pgsql.sh    # PostgreSQL

Code Quality

# Full suite: tests + cs-check + PHPStan + Psalm + deptrac
composer testsuite

# Code style check / fix
composer cs-check
composer cs-fix

# Static analysis (PHPStan level 7)
composer stan

# Psalm analysis
composer psalm

# Architecture rules (deptrac)
composer deptrac

Contribute

Everybody is welcome to contribute to Propel! Just fork the repository and create a pull request.

Requirements for contributions:

Use declare(strict_types=1) in all PHP files
Follow Spryker coding standards (extended from PSR-12)
Pass PHPStan level 7 analysis
Include unit tests for your changes

Have a look at the test suite guide for more details about test development in Propel.

Thank you!

License

MIT. See the LICENSE file for details.

dennisvanbeersel / propel

Maintainers

Package info

Statistics

Security