Propulsion

What is Propulsion?

Propulsion is an object-relational mapper (ORM) for PHP: you describe your database as an XML schema, generate a full set of typed Object Model and Query classes from it, and your application code talks to those generated classes instead of hand-written SQL. It’s a hard fork of Propel 1, renamed and modernized to target current PHP — Phing’s build tooling replaced by a plain Symfony Console application, PostgreSQL promoted to the default and best-supported database, and useQuery()/endUse() given a closure-scoped withQuery() replacement that plays nicely with static analysis and IDE autocompletion. See Migrating from Propel 1 if you already know Propel.

Code-generated, not reflective

A schema compiles to real, typed PHP classes ahead of time — no runtime annotation parsing or reflection-driven mapping.

PostgreSQL-first

PostgreSQL 16+ is the default and most feature-complete target; MySQL, SQLite, Oracle, and MSSQL are also supported.

Modern PHP 8.5+

Typed properties, enums, and current PHP syntax throughout — no PHP 5-era conventions left standing.

No Phing required

Phing has been ripped out entirely. Code generation and schema tooling run through a Symfony Console application, bin/propulsion.

Get started

The latest stable version is v3.0.0 (see Upgrading from 2.x to 3.0 if you’re coming from 2.x). Install it from Packagist with Composer:

composer require quioteframework/propulsion

Write a schema, generate your models, and start querying:

bin/propulsion model:build schema.xml --output-dir=src/Model --database=pgsql

$books = BookQuery::create()
    ->withAuthorQuery(fn ($author) => $author->filterByFirstName('Jane'))
    ->find();

See Installation for requirements, and Building your schema to go from an XML schema to generated classes. Already on 1.0? See Upgrading from 1.0 to 2.0.

Explore

Basic CRUDCreate, read, update, and delete rows through generated Object Model classes.

RelationshipsForeign keys, joins, and the withQuery()/withQuery() family.

Migrating from Propel 1What changed, what's still compatible, and the automated Rector rule for useQuery()/endUse().

BehaviorsReusable schema-level features: timestampable, sortable, i18n, soft delete, and more.

Supported databasesThe five supported engines, their minimum versions, driver setup, and the per-platform differences worth knowing.

Advanced queriesCTEs, window functions, set operations, subquery filters, JSON path extraction, vector distance queries, and query plans.

Global query filtersA predicate applied to every query on a model — soft delete and multi-tenancy without repeating a condition.

Observing queriesQuery observers for slow-query logging, timing metrics, bound parameters, and captured rows you can leave on in production.

OpenTelemetry tracingA CLIENT span per statement, exported over OTLP/HTTP — turned on from configuration, with no application code.

Connection resilienceDropped-connection detection, pre-checkout liveness pings, and transaction retry on deadlocks.

Using Propulsion from Quiote

Propulsion also ships as one of Quiote’s first-class database adapters — see Databases: Propulsion for how the two fit together, though Propulsion itself is a standalone ORM with no dependency on the Quiote framework.

Credit where it’s due

Propulsion exists only because of the work of the Propel community over more than a decade. It is a hard fork of Propel 1, originally created by Hans Lellelid (based on the Apache Torque project) and later maintained by the wider Propel community — notably David Zuelke, François Zaninotto, and William Durand — along with everyone who filed issues, wrote behaviors, and contributed patches over Propel 1’s lifetime. Propel 1’s own documentation, most of which this section is adapted from, lives at propelorm.github.com, and its CHANGELOG/WHATS_NEW history up to the 1.6.1 release this fork branched from is preserved in this project’s archaeology/ folder.

Propel 1 development had wound down and the project was effectively unmaintained by the time this fork began; Propulsion renamed the project (Propel* → Propulsion*), replaced Phing with a plain console application, and continues it with modern PHP and ongoing bug fixes. It’s distributed under the same MIT license as Propel 1 — see the LICENSE file, which carries both the original Propel copyright holders and the Propulsion contributors, and NOTICE.md for the full attribution.

Note that Propel 2 is a separate, incompatible codebase (a later, Doctrine-inspired rewrite) — Propulsion forks Propel 1, the Active Record-style ORM configured via XML schema files, not Propel 2.