Crudl Bundle Laravel Package

Getting Started

Framing note: softspring/crudl-bundle is a Symfony bundle, not a Laravel package — there is no service provider, no config/crudl.php, and no Artisan command. "Day-to-day" here means Symfony controllers, Doctrine, Symfony Forms and Twig. If you are in a Laravel codebase, this package is not the right tool.

• Install with composer require softspring/crudl-bundle and enable it in config/bundles.php (Flex recipe normally handles both).
• Hard dependencies to confirm in your app: Doctrine ORM (entities + EntityManagerInterface), Symfony Forms, Twig, and a paginator integration.
• Look here first: the bundle's CrudlController base class and its per-action configure* methods. That is the entire contract — everything else is convention.
• First use case: one admin CRUD for one entity. Create a controller extending the base class, implement the abstract hooks (getEntityClass(), getFormTypeClass(), getBaseRouteName()), point routing at it, and you get list/create/read/update/delete for free.
• For v5.6.0 specifically: the release note is an autogenerated changelog link with no described changes. Pin ^5.6 and read the actual compare diff (v5.5.10...v5.6.0) before assuming it is a safe drop-in.

Implementation Patterns

• One controller per entity, thin. Keep the controller to configuration and overrides only; put real business logic in services or entity methods. The base class is opinionated about flow, not about your domain.
• Configure, don't fork. Use the per-action configurators (list/create/read/update/delete) to toggle behaviour — allowed actions, page sizes, redirect targets, flash messages, template paths — rather than overriding the action methods wholesale.
• Pre/post hooks for side effects. Use the lifecycle hooks around create/update/delete (e.g. post-persist) rather than duplicating the persist/flush cycle yourself; you will otherwise fight the bundle's own transaction ordering.
• Filters and search. Implement a filter form type for the list action and wire it through the controller's filter-form hook. This is the intended extension point — do not hand-roll query building in a listAction override.
• Security. Gate actions with Symfony's security layer (voters / isGranted) inside the configurators or via route-level #[IsGranted]. Per-action toggling is cleaner than one big voter for the whole controller.
• Templates. Override the bundle's Twig templates per-controller by setting a template path, falling back to @SoftspringCrudl/... for anything you don't override. Prefer per-controller overrides over editing vendor templates.
• Custom actions. Add a normal controller method plus a route, and reuse the base class's helpers for entity lookup and rendering. This is the cheapest path to "export CSV" or "duplicate" buttons.
• Menus/navigation. Wire the generated route names into your admin menu rather than hardcoding URLs, so base-route-name changes propagate.

Gotchas and Tips

• getBaseRouteName() collisions are the #1 source of confusing bugs. Route names are derived from it; two controllers with overlapping prefixes will silently shadow each other. Verify with bin/console debug:router.
• Routing style must match your Symfony version. Attribute/annotation routing on the controller is required for the bundle to expose its actions; a controller with no routes appears to "do nothing" and gives no error.
• Doctrine identity map. Long admin sessions and multi-action flows can serve stale entities. If you override the persist/flush path, be deliberate about refresh() and about not holding the EM across actions.
• Form types must be Symfony AbstractType. Passing a Laravel-style form request or a validated DTO will not work; the form factory expects a real form type with a configured data_class.
• v5.6.0 release note is empty. The changelog body only links to the GitHub compare view. Treat the bump as a minor release, but diff it — minor versions of this bundle have historically touched abstract-method signatures, which break subclasses at runtime rather than at install time. Run your test suite against the new constraint before merging.
• Debugging: debug:container to confirm the bundle's services registered, debug:router for route wiring, and the Symfony profiler for the Doctrine queries each action emits. Nearly every "CRUDL is slow/wrong" report resolves to an N+1 in a list query or a misconfigured filter form.
• Extension points, in order of preference: configurators → lifecycle hooks → custom actions → Twig overrides → service decoration. Subclassing the abstract action classes directly is the last resort and is the most upgrade-fragile surface.
• Composer constraint discipline. Because the API surface is "subclass and override", pin ^5.6 rather than a floating ^5, and re-read the diff on each minor bump.