Grid Bundle Laravel Package

Getting Started

Before anything else: this is a Symfony bundle, not a Laravel package. It has no service provider, no Eloquent integration, and its data layer is Doctrine (ORM / DBAL / ODM / a plain array driver). A Laravel developer's day-to-day use is therefore realistic in two situations only: you are working inside a Sylius or Symfony app, or you want to steal the configuration-driven grid model (close to Filament resources or Nova's make() chains, but expressed as declarative config + tagged services).

Minimal path:

composer require sylius/grid-bundle

// config/bundles.php
Sylius\Bundle\GridBundle\SyliusGridBundle::class => ['all' => true],

Define a grid (YAML is still the fastest way to see it work):

# config/packages/sylius_grid.yaml
imports:
    - { resource: '../grids/' }

sylius_grid:
    grids:
        app_admin_product:
            driver:
                name: doctrine/orm
                options:
                    class: App\Entity\Product
            fields:
                id:      { type: string, label: ID, sortable: true }
                name:    { type: string, label: Name, sortable: true }
                enabled: { type: boolean, label: Enabled }
            filters:
                name:    { type: string }
                enabled: { type: boolean }
            actions:
                main:
                    create: { type: create }
                item:
                    update: { type: update }
                    delete: { type: delete }
            limits: [10, 25, 50]

Then resolve the grid and render it from a controller (service ids are all under sylius_grid.* — bin/console debug:container sylius_grid is your first stop; in Sylius, copy ResourceController::indexAction + ResourceGridViewFactory verbatim rather than re-inventing the parameter wiring) and in Twig:

{{ sylius_grid_render(grid, '@SyliusUi/Grid/_default.html.twig') }}

Where to look first, in order: the Stack docs (stack.sylius.com/grid), then src/Bundle/Builder/ in the repo (field/filter/action factory classes — this is the real API surface), then the test application's grid configs, which double as working examples. bin/console make:grid scaffolds a PHP grid builder.

First use case: an admin index page for one Doctrine entity with sortable columns, a text filter, and pagination. That is 90% of what this bundle is for, and it is genuinely fast to get to.

Implementation Patterns

Declarative vs. PHP builders. YAML grids are fine for static admin screens but they rot in large codebases. Since v1.11 the supported direction is PHP: implement GridBuilderInterface::buildGrid(), register the class as a service tagged sylius.grid, and compose with the builder factories:

final class ProductGrid implements GridBuilderInterface
{
    public function buildGrid(GridBuilderInterface $gridBuilder): GridBuilderInterface
    {
        return $gridBuilder
            ->addField(StringField::create('name')->setLabel('app.ui.name')->setSortable(true))
            ->addField(BooleanField::create('enabled')->setLabel('app.ui.enabled'))
            ->addFilter(StringFilter::create('name'))
            ->addActionGroup(ActionGroup::create('main')->addAction(CreateAction::create()))
            ->addActionGroup(ActionGroup::create('item')->addAction(UpdateAction::create()));
    }
}

Treat the exact factory names as version-sensitive; grep src/Bundle/Builder/ rather than trusting blog posts.

Grid inheritance. YAML grids support extends: — define a base_admin_grid with your standard actions, limits, and bulk actions, then let each resource grid override only driver, fields, and filters. This is the single biggest maintainability lever in the bundle and it has no clean equivalent in the fluent API, so hybrid setups (base YAML + PHP child) are common.

Repository-method driver. Rarely advertised, frequently needed: if the default query builder gives you N+1s on associations, point the driver at a custom repository method instead of fighting the config.

driver:
    name: doctrine/orm
    options:
        class: App\Entity\Product
        repository:
            method: createAdminListQueryBuilder

Do the LEFT JOIN + addSelect for related entities/translations there, and sorting on association paths becomes cheap.

Sorting on non-column values. Use a dedicated sorting block on the field rather than sortable: true, especially for translated or embedded properties (sorting: { path: translation.name }). Keep the visible field enabled: false and add a separate sort-only field if the column shouldn't render.

Custom column rendering. The twig field type with a template option is the escape hatch for anything the stock types don't cover (badges, avatars, money formatting). Reach for a custom FieldTypeInterface only when you need the same rendering in three or more grids — the type is registered with a sylius.grid_field tag.

Filter types you'll actually use: string, boolean, date, entity (with multiple), exists, numeric, select. The entity filter needs the target class in options; the multi-select form of it had a long-standing bug fixed during the 1.11 alphas, so pin a recent version if you rely on it.

Reuse the parameter contract. Everything is query-string driven: criteria[name]=foo, sorting[name]=desc, page=2, limit=25. That means grid state is bookmarkable and testable with plain HTTP tests — write functional assertions against the query string rather than unit-testing the grid object.

Gotchas and Tips

• Security floor: >=1.10.2. v1.10.1 patched a DQL injection through sorting parameters (GHSA-2xmm-g482-4439); v1.10.2 re-allowed sorting on declared-but-disabled fields. Anything older is both vulnerable and subtly wrong.
• No Eloquent, and a custom driver is not a weekend project. The driver contract covers filtering, sorting, and pagination query building; the array driver is the only framework-agnostic one. If you're porting this pattern to Laravel, port the idea (config object → field/filter/action collections → adapter), not the code.
• Everything is cached. Grid definitions are compiled config. After editing PHP builders you need cache:clear, and in dev you'll burn ten minutes before remembering that.
• Labels are translation keys, always. label: Name "works" only because the translator falls back to the key. The moment you add a translation catalogue, Name may collide or disappear — namespace your keys (app.ui.name).
• Sorting fails loudly, not silently. Unknown fields throw; Twig-typed fields cannot be sorted. Nullable-path sorting and PostgreSQL LIKE case-sensitivity were fixed in v1.8.0 / v1.11 alphas respectively — old versions will bite you on Postgres.
• limits must be declared. Passing ?limit=500 when limits: [10, 25, 50] is not in the config silently falls back to the default. This looks like a bug and isn't.
• Rendering is not batteries-included standalone. sylius_grid_render needs a template; the canonical one lives in Sylius UI (@SyliusUi/Grid/_default.html.twig). Outside Sylius you supply your own Bootstrap/Tailwind markup — budget half a day for the table, filter form, sorting links, and pager. Pagerfanta 3 support landed in v1.11, so mixed Pagerfanta versions across your app produce confusing template errors.
• Debugging workflow: bin/console debug:container --tag=sylius.grid_filter (and sylius.grid_field, sylius.grid_driver, sylius.grid_action) enumerates every registered type including third-party ones. When a type: in YAML is "not found", it's almost always a missing tag, not a typo.
• Extension points worth knowing: FieldTypeInterface (sylius.grid_field), FilterTypeInterface (sylius.grid_filter), driver (sylius.grid_driver), action type (sylius.grid_action). Everything else in the bundle is composition over those four tags.
• Maturity reality check: ~134 stars and effectively a component of Sylius maintained by the Sylius core team. Issues often get triaged in the main Sylius/Sylius tracker (the README points there), so search two repositories before filing. The API is stable but the docs lag the PHP builder surface by a release or two — read the source when in doubt.