Propel Datagrid Bundle Laravel Package

Getting Started

Before writing a single line of integration code, understand the shape of this package: it is a Symfony 2.x bundle for Propel ORM, not a Laravel package. There is no service provider, no facade, no Eloquent integration. If you are in a Laravel codebase, "getting started" really means deciding whether you can justify running Symfoný's bundle system and Propel side-by-side with Eloquent, which in almost every case you cannot.

Assuming you are working in a legacy Symfony 2 project that already uses Propel:

1. composer require spyrit/propel-datagrid-bundle — the bundle wires the underlying spyrit/propel-datagrid library (the datagrid abstraction itself) into the Symfony DI container. The bundle is thin; the real API lives in the dependency.
2. Register Spyrit\PropelDatagridBundle\SpyritPropelDatagridBundle in app/AppKernel.php.
3. Look first at the bundle's Resources/config/services.xml and the datagrid base class in the spyrit/propel-datagrid library — the bundle has little code of its own and the useful documentation is on the underlying library, not here.
4. First use case: take an existing PropelQuery (e.g. BookQuery::create()), wrap it in a datagrid definition declaring sortable columns and filters, hand it to your controller, and render an HTML table via the bundled Twig extension. That is the entire happy path — sort, filter, paginate a Propel query in a Twig template.

If you are evaluating from scratch with 3 stars and 0 dependents, treat the first session as a feasibility spike rather than a real adoption: verify the Propel version constraint and Symfony version constraint actually resolve in your app before committing.

Implementation Patterns

Datagrid definition per entity. The idiomatic pattern is a concrete datagrid class per list view, extending the library's base datagrid, that declares columns, default sort, page size, and available filters. Controllers stay thin: instantiate or fetch the datagrid from the container, bind the request, pass it to the view.

Controller → Twig flow. The Symfony 2 pattern is: build query → instantiate datagrid → $datagrid->bind($request) so it reads page, sort, order, and filter params from the query string → pass to Twig → the Twig helper renders headers (with sort links) and rows. Keep this in one action; don't split read/sort/filter into separate endpoints.

Filter binding. Filters typically map to Propel query methods (filterBy*, where). Because the underlying model is Propel, filter callbacks receive a ModelCriteria and can chain arbitrary Propel criteria — this is the most powerful extension point and the one you will use most. Reuse the same filter definitions across an HTML list and an export (CSV/XLS) by serializing the bound datagrid.

Integration with routing and services. Register datagrids as container services if they need dependencies (repositories, security checks, request-aware filtering), otherwise construct them inline with plain PHP. If you go the service route, tag them so you can centralize column/permission configuration.

AJAX refresh. Common production pattern is to render the table inside a partial and hit the same controller via AJAX with ?_pjax-style parameters; because state is entirely in the query string, the datagrid is stateless and plays well with this.

Gotchas and Tips

This is a Symfony 2 / early-3 era bundle. The bundle's structure (AppKernel registration, services.xml, no autowiring) assumes that generation. Do not expect it to work in Symfony 4+ without significant surgery, and do not expect Laravel compatibility at all — there is no bridge.

Propel is not Eloquent. There is no Builder, no ->paginate(), no model events. You are working with ModelCriteria / PropelQuery, filterByX, and ->find() / ->paginate(). Any Laravel developer picking this up must learn Propel's query API first; the bundle docs will not teach you that.

Running two ORMs in one app is the real pitfall. If you are considering this package because a Propel dataset already exists, understand you are inheriting Propel's schema, connection, and migration tooling alongside Eloquent. Budget for this before anything else.

Thin bundle, real API is upstream. The vast majority of bugs you hit will be in spyrit/propel-datagrid, not this repository. File issues and read code there. Also check the exact version constraint this bundle declares on that library — that dependency is unmaintained in all likelihood.

Extension points. Subclass the datagrid to override column rendering, header templates, and filter handling. Wrap the Twig rendering in your own macro if you need a different markup style; don't try to override the bundle's Twig template path unless you are comfortable with Symfony's resource override conventions.

Debugging. When a list is wrong (missing rows, wrong sort, wrong page), the fastest path is to dump the generated SQL from the Propel criteria — the bundle does not do anything magical, everything reduces to a ModelCriteria. Bind and immediately var_dump((string) $criteria) before touching the datagrid layer.

Config quirks. Because there are effectively no dependents (0) and 3 stars, there is no community to fall back on for configuration questions. Treat every config option as "verify by reading Configuration.php" rather than assuming documented behavior. Expect the README to be incomplete or to reference the underlying library's docs.

Honest recommendation. For a new Laravel project, use an Eloquent-based datagrid (e.g. a maintained Laravel datatables package) and do not attempt to bolt this on. For a legacy Symfony 2 + Propel app that already lists data, this package is a reasonable thin convenience over hand-rolled pagination — but verify version constraints and expect to maintain it yourself, because at 0 dependents you will be the only one filing bugs.