Lister Twig Bundle Laravel Package

Getting Started

This bundle is glue between the underlying povs/lister-bundle and Twig, so treat it as a pair. Before anything else, read the composer.json of both packages and verify the constraints against your PHP/Symfony/Twig versions — this is a zero-star, effectively unmaintained package and the constraints are likely pinned to old Symfony (3.x/4.x-era) releases. If your app is on Symfony 5.4+, expect to either fork it or vendor-patch it before you get a first render.

Minimal path:

1. composer require povs/lister-bundle povs/lister-twig-bundle
2. Register both bundles (AppKernel::registerBundles() on legacy Symfony, config/bundles.php on Flex).
3. Confirm the Twig extension is loaded: bin/console debug:twig | grep -i list and bin/console debug:container | grep -i lister. If the extension isn't there, nothing else will work — check the Resources/config/services.xml and fix the service definition before writing templates.
4. First use case: render a single read-only list. Define a list type class using whatever base class the core lister-bundle exposes (AbstractListType / a buildList() method in most lister implementations), add two or three simple columns, instantiate it from a controller via the lister service, and pass the list to a template where the Twig bundle's render call takes over.

Where to look first, in order: the povs/lister-bundle README (the concepts — lists, columns, list types — live there, not here), then Resources/views/ in this repo to see the default table markup, then Resources/config/ to learn the real service IDs. The repo itself is thin; the value is in knowing what it wires up.

Implementation Patterns

Controller-rendered lists (Twig type). The dominant pattern for this bundle: build the list in the controller, hand it to the template, let the Twig list type render the table. Keep the controller thin — the list type class holds column definitions, the controller holds only the list instance and its data source.

The Ajax list type. The second list type renders a lightweight shell (table skeleton plus a small JS bootstrap) and fetches rows from a data endpoint. The pattern is a pair of actions: one that renders the page with the Ajax list type, one that returns the list payload for the front-end to consume. Both must reference the same list type class or the shell and the data will disagree about columns, sorting, and page size. Wire the data route explicitly and pass it into the list configuration rather than hardcoding it in the JS.

Overriding the default templates. Don't edit Resources/views in place — override by convention. On legacy Symfony that's app/Resources/PovsListerTwigBundle/views/...; on Flex it's templates/bundles/PovsListerTwigBundle/.... Override the smallest template that carries the markup you care about (usually the table body and the pagination fragment) rather than the top-level one, so you don't freeze upstream changes you'd otherwise inherit.

Per-column Twig blocks. The usual extension point for custom cell rendering is a column that names a Twig block or template fragment. Use this instead of |raw concatenation in the list type — it keeps escaping in Twig's hands and keeps presentation out of PHP. Custom column types that need a service (formatter, URL generator) should be registered in the container and injected, not new'd inside buildList().

Filters, sort, and pagination as a unit. Sort links, filter forms, and page links all round-trip state. For the Twig type that state usually lives in the query string; for the Ajax type it must be serialized into the fetch request. Centralize the state-building in one place (a small helper or the list's own state object) so both list types produce identical URLs. This is the single most common place integration breaks.

Reuse across controllers. Extract a list type per domain entity and register it as a service tagged with whatever tag the lister uses; then any controller can request it by class name. This scales far better than building lists ad hoc.

Gotchas and Tips

• Maintenance risk is the top gotcha. Zero stars, zero dependents, no recent activity. Assume no security advisories will land and no one will fix a Twig API break. Pin the version and budget for vendoring the two bundles into your repo if this is production code.
• Two bundles, one mental model. Most confusion comes from reading this repo looking for list/column semantics — they're defined upstream. Debug against povs/lister-bundle first.
• Twig template namespace moves. The override path differs between Symfony versions (app/Resources/... vs templates/bundles/...). If your override silently doesn't apply, you're on the wrong path for your framework version — verify with debug:twig that it sees your file. -Ajax list double-rendering. A frequent symptom: the shell renders rows and the Ajax fetch renders them again, because both list instances are "visible." Ensure the shell variant renders an empty body and the data action is the only row producer.
• State leakage between requests. If list state (filters/sort/page) is stored in session rather than the query string, two tabs or two users on a shared session-bound cache can stomp each other. Prefer query-string state; verify by opening the same list twice in two tabs.
• Escaping in custom columns. Anything a custom column returns is likely marked safe downstream. Escape inside the column or return a Twig-rendered fragment — never concatenate user data into markup.
• Container compilation is where old bundles die. Expect debug:container failures on newer Symfony (deprecated service definitions, missing public: true, autowiring assumptions). Patch Resources/config/services.xml directly; the fix is usually mechanical.
• Debugging render output. Use {% dump %}/dump() on the list view object to inspect columns and state; most "wrong column order" and "empty list" issues are visible there rather than in the template.
• Extension points worth knowing: custom list types, custom column types, the template override hierarchy, and the data-route configuration for the Ajax type. Those four cover nearly every day-to-day change; anything else probably means editing the bundle in vendor/.