Datagrid Bundle Laravel Package

Getting Started

First, a framing note: rollerworks/datagrid-bundle is a Symfony bundle, not a Laravel package. v0.6.1 is purely a compatibility patch (Fix compatibility with Symfony 3.3, #9) — it changes nothing about the public API. For a Laravel codebase the practical move is to depend on the framework-agnostic core (rollerworks/datagrid) and ignore the bundle's Symfony DI layer entirely.

Minimal steps:

composer require rollerworks/datagrid

If you do install the bundle (e.g. shared codebase with a Symfony app), note that it pins Symfony DI/HttpKernel behaviour; v0.6.1 only widens that pin to include Symfony 3.3.

Where to look first, in this order:

1. DatagridFactory (Rollerworks\Component\Datagrid\DatagridFactory) — the entry point; createDatagrid($name, $dataProvider).
2. ColumnTypeInterface / AbstractColumnType — how columns are declared and resolved.
3. DataProviderInterface — the seam you must implement for Eloquent, since the shipped providers are Doctrine ORM/DBAL only.
4. The bundle's DependencyInjection/Configuration.php — only if you're reading it as documentation for how column types are registered into a container.

First use case: a paginated, sortable admin index over an Eloquent query. Build a factory in a service provider, register the built-in column types (text, number, datetime, action), implement an Eloquent data provider, and render the resulting DatagridView in a Blade component.

Implementation Patterns

Service provider wiring. Bind a singleton DatagridFactory and register column types explicitly — the bundle normally does this via a compiler pass, which you don't get in Laravel:

$this->app->singleton(DatagridFactory::class, function () {
    $factory = new DatagridFactory();
    $factory->registerColumnType(new TextType());
    $factory->registerColumnType(new NumberType());
    $factory->registerColumnType(new DateTimeType());
    $factory->registerColumnType(new ActionType());
    return $factory;
});

Custom Eloquent data provider. This is where nearly all your integration work lives. Implement DataProviderInterface (getRows(), getTotalCount()) over a Builder, translating the datagrid's sort/filter state into orderBy() / where() calls before paginate().

Grid definition as a class. Rather than building grids inline in controllers, extract a DatagridType-ish class per resource (UserGrid, OrderGrid) configured with columns and options. This mirrors the Symfony form-type idiom and keeps controllers to three lines: create, handle request state, return view.

Request handling. Read sort column/direction and filter values off the Request, apply them to the datagrid before fetching rows, and pass the DatagridView plus the paginator to the view. Keep the state in the query string so links are shareable and the browser's back button works.

Rendering. The bundle's Twig themes are not usable from Blade. Two options: render a Blade partial that iterates $view->getColumns() / row cells (cleanest, keeps escaping under Blade's control), or expose the view as JSON for a JS table. Don't try to port the Twig themes — they're thin loops anyway.

Config. If you installed the bundle, its tree lives under rollerworks_datagrid. In Laravel, mirror anything you need into config/datagrid.php and read it from the provider; don't attempt to load the bundle's YAML/XML service definitions.

Gotchas and Tips

• Version 0.6.x is pre-1.0. Minor bumps can and do break BC. Pin with ~0.6.1 and read every changelog. This release being a one-line Symfony-compat fix is a good signal that maintenance is low-velocity — budget for vendoring or forking.
• Don't let the bundle into a Laravel app. It pulls Twig and Symfony DI as hard dependencies. rollerworks/datagrid alone is far lighter.
• The Symfony 3.3 fix tells you where the bundle's fragility is: the DI extension and compiler passes. Any Symfony major bump historically required a patch here. If you're on the Symfony side of the fence, test after upgrading Symfony minor versions, not just majors.
• Doctrine-shaped assumptions leak into the docs. Every example uses Doctrine; the DataProviderInterface is genuinely the only contract, but sample code and community answers will mislead you. Write your Eloquent provider first and treat it as the source of truth.
• Column type registration order matters. Types must be registered before createDatagrid() resolves column types; a missing type throws at grid-construction time, not at render time, which makes the stack trace point at your grid class rather than your provider.
• Sorting state is not persisted for you. Unlike Symfony's session-backed form handling, you must round-trip sort/filter state yourself. Forget it and every page-2 click resets the grid.
• Debugging: dump($view->getColumns()) and the row arrays from your provider. Nearly every "empty grid" report is getTotalCount() returning 0 because a filter was applied before the count query, or a missing select() on the count.
• Extension points worth knowing: custom ColumnType for domain-specific cells (status badges, money formatting), a decorator around your data provider for caching counts, and DatagridExtensionInterface if you need to hook grid creation globally.
• Escape at the edge. The datagrid produces raw values; do not mark them safe. Blade's {{ }} is your protection — never {!! !!} on cell values coming from user-editable columns.