Propel Bundle Laravel Package

Getting Started

• Reality check first: PropelBundle is a Symfony bundle, not a Laravel package. Its service provider, config tree, and console commands assume a Symfony kernel, so composer require into a Laravel app is not a "just works" path. If you want Propel in Laravel, install propel/propel directly and use this bundle as a reference implementation for how to bootstrap Propel (connection config, build pipeline, runtime setup).
• Where to look first: the bundle's DependencyInjection configuration (connection credentials, propel.paths, build-time settings) and its Command/ directory (propel:build, propel:model:build, propel:migration:diff, propel:sql:build, propel:sql:insert). Those commands define the day-to-day surface area.
• Minimal Laravel-side steps: publish a config/propel.php equivalent, create a schema.xml, generate model classes under app/Propel/..., register a PSR-4/classmap autoload entry, and call Propel::setConfiguration() / Propel::initialize() once from a service provider.
• First use case: reverse-engineer an existing database into schema.xml, generate model + query classes, then run one read through a generated XxxQuery class. That proves the wiring before you touch writes.

Implementation Patterns

• Schema-first workflow: treat schema.xml as the source of truth, version it, and regenerate classes in CI (propel model:build) instead of editing generated code. In Laravel, hook this into a Composer script or a thin Artisan wrapper that shells out to the Symfony console tooling.
• Connection wiring: mirror the bundle's pattern — one Propel configuration per connection, Propel::setConfiguration() at boot, and Propel::initialize() behind a static guard so it runs once per process (important under Octane).
• Repository layer: wrap generated XxxQuery classes behind your own repositories or action classes. Generated query objects are static and global-state-bound; hiding them keeps tests swappable and stops Eloquent-style assumptions from leaking in.
• Migrations: use Propel's diff-based migration against schema changes if you need it, but keep Laravel's own migrations for framework tables. Two migration systems coexist fine as long as they never own the same table.
• Reads and writes: ModelQuery::create()->filterBy...()->find() for reads, $obj->save() for writes; hydrate into DTOs or API resources at the boundary. Propel objects are not Eloquent models — no $casts, no observers, no refresh() chains.
• CI integration: run model build plus propel sql:build / sql:insert against a throwaway DB each pipeline, then run the suite. This catches schema/class drift early.
• Version pinning: recent 7.1.0.x releases are maintenance-only, so pin to a known patch (7.1.0.3) and upgrade deliberately rather than floating ^7.

Gotchas and Tips

• Not Laravel-native: no facades, no Artisan commands, no queue/event integration out of the box. Anything you expect from php artisan migrate has to be a wrapper you write.
• Composer conflicts: the bundle constrains symfony/* packages, and Laravel ships Symfony components too — version ranges can collide. Run composer why-not before blaming the bundle, and use Propel core alone if you only need the ORM.
• Removed more deprecated content in 7.1.0.3: cleanup releases are usually safe, but that phrase is the one that bites if you subclassed or called internals. Grep for anything dropped between 7.1.0.2 and 7.1.0.3 before upgrading, and run the build pipeline in CI first.
• Bootstrap order: Propel's static configuration is process-global. Initializing inside a request-scoped provider costs you on every request and risks stale state under Octane. Do it once, in a dedicated bootstrap or a guarded booted callback.
• Generated code and autoloading: generated classes need a PSR-4 or classmap entry. Forgetting it is the most common "class not found" after a fresh model:build.
• Caching: Propel's runtime config and query caches are separate from Laravel's. php artisan cache:clear does not clear them; use Propel's own cache tools or bump the runtime config path.
• Debugging: log the resolved Propel::getConfiguration() at boot to confirm DSN and classpath. Most "wrong database" reports are config-merge issues, not Propel bugs.
• Extension points: the bundle's behaviors (timestampable, sluggable, etc.) are reusable in a Laravel context — copy them into your schema rather than reimplementing in app code. The service-provider wiring is also a reasonable template if you later write a small Laravel bridge.