Crudit Bundle Laravel Package

Getting Started

Read this before composer require: CruditBundle is a Symfony bundle, not a Laravel package. There is no service provider, no config publish tag, no Blade views, and no Vite/Mix integration. composer require 2lenet/crudit-bundle inside a Laravel app will install files you cannot boot. The realistic day-to-day decision for a Laravel developer is one of two paths:

1. Satellite admin app (recommended if you actually need this feature set). Stand up a small Symfony application alongside your Laravel app, pointed at the same database read-mostly, put it behind the same SSO/reverse proxy on something like admin.internal, and let Crudit generate the back-office. Your Laravel app stays untouched; Crudit owns list/show/form/export for internal users.
2. Mine it for patterns, don't install it. If you only want the admin-CRUD ergonomics, the config-class + datasource + filterset decomposition below is worth copying into a Laravel package of your own. Adopting the bundle itself into a Laravel monolith is not a supported move.

Assuming the satellite-app path, minimal first steps:

• composer require 2lenet/crudit-bundle. Webpack Encore is a hard requirement and the app must already have a Symfony security firewall configured — the layout will not render without one.
• npm install bootstrap@5 sass sass-loader @fortawesome/fontawesome-free easymde --save, then wire Encore.
• Extend the shipped layout in your base template:

  {% extends '@LleCrudit/layout/sb_admin/layout.html.twig' %}
  

  with encore_entry_link_tags('app') in stylesheets and encore_entry_script_tags('app') in javascripts (call parent() first).
• Import ../styles/app.scss in assets/js/app.js, and inside assets/styles/app.scss import ../../vendor/2lenet/crudit-bundle/assets/sb-admin/css/app.scss.

Where to look first, in this order: doc/config.md (bundle config), doc/webpack_encore.md (the part that actually breaks), doc/crud.md (the four-piece anatomy), then doc/filter.md. doc/design.md is marked "TO COMPLETE" — do not expect architectural guidance there.

First use case: one read-only CRUD over a single entity — e.g. Order — with a list view and a show view, no form, no batch actions. Get the datasource returning rows and the field list rendering before you touch filtersets, exports, or workflows. Most of the failure modes in this bundle surface at the datasource/layout boundary, and you want to hit them with one screen, not ten.

Implementation Patterns

The four-piece anatomy is the whole mental model. Every CRUD is: an independent controller, a CrudConfig class, a DataSource, and an optional FilterSet. Keep the controller nearly empty and push everything declarative into the config class — that is what makes the CRUD greppable six months later.

Datasource is your integration seam. The README is explicit that the list view "needs a Datasource but is not bounded to Doctrine or any ORM," while also noting Doctrine is required "for the pre-version." Treat that as: Doctrine is the only well-trodden path, but a custom DataSource is a legitimate extension point. For a Laravel shop this is the bridge — implement a DataSource that calls your Laravel JSON endpoints or Eloquent-backed tables. Budget real time: you are also implementing pagination, sorting, filtering, and export iteration yourself, because the Doctrine path gets those for free.

List view carries pagination, sorting, item actions (show/edit/delete), list actions (add/export CSV/Excel), list grouping, batch actions, and row coloring via a class returned by the entity. Add grouping before you add columns — it is the cheapest way to keep wide admin tables readable.

Show view gives you tabs and sublists for related data. This is the highest-leverage feature for order→line-items, user→sessions, invoice→payments style screens; it is also where subtotals and totals columns have been actively developed (1.17.4, 1.19.x). Use tabs to separate related collections rather than building nested routes.

Form view is a plain Symfony FormType. You write the type; Crudit supplies Datetime/Entity types, a TomSelect-based autocomplete entity dropdown, EasyMDE markdown, and a DoctrineFormGuesser that swaps in Crudit types automatically. If the guesser fights you, override per-field in the config rather than disabling it globally.

Filtersets are reusable outside Crudit (doc/filterset_controller.md). If you already have a bespoke Laravel-backed controller, this is the one piece worth lifting conceptually: define filters once, reuse across the CRUD list and your own endpoints (e.g. a JSON autocomplete route).

Operational patterns worth adopting:

• Hide bricks, tabs, and actions based on the request (1.18.4) instead of maintaining two configs.
• Dynamic list/sublist sorting at runtime (1.20.0) for saved-view style UX.
• Row coloring driven by an entity method keeps status semantics in the domain, not the template.
• Reuse the Crudit layout (@LleCrudit/layout/sb_admin/layout.html.twig) for one-off admin screens so menus, brand, and auth chrome stay consistent; menu and brand are configured independently of any CRUD.
• Treat batch actions as a separate privilege from edit. They bypass per-entity form validation by design.

Gotchas and Tips

• Asset pipeline is the first wall. Encore is mandatory; if your Laravel app runs Vite, there is no shared path. Keep the admin app's assets in its own build. Bootstrap 5 is pinned and Tailwind will collide — never share a stylesheet between the two.
• SCSS import order is load-bearing. All your SCSS files must be imported before the Crudit SCSS import. Get it backwards and your overrides silently lose to vendor styles with no error.
• Security is a bootstrap prerequisite, not a later task. Add the firewall before you evaluate the layout, or you will debug a blank page for an hour.
• Pin exact versions and read the release notes. The project ships very frequently, and several releases are behavioral rather than cosmetic: 1.17.0 changed CRUD return management, 1.20.2 reworked the referer system, 1.17.6 fixed the wrong field being used by filters. Lock to a patch version and upgrade deliberately.
• Redirects are referer-driven. Return-to-list flows depend on the referer header. Reverse proxies, subpath deployments, and strict Referrer-Policy headers will quietly dump users on the wrong page after save. Test behind the proxy, not just on localhost.
• Debugging order: config class → datasource output → field definition → template. Almost every "blank cell" is the datasource returning a shape the field type does not expect, not a Twig bug.
• Filter edge cases have a history. If a filter appears not to apply, check whether it is bound to the right field (1.17.6) and whether the state survives a select interaction (1.19.0, workflow filters). Add a smoke test per filter.
• Excel export loads phpoffice/phpspreadsheet. It is heavy. Confirm whether export honors the current filter/pagination scope before shipping it to users on large tables, and watch memory on wide exports.
• Ecosystem risk is real. 16 stars, zero dependents, vendor-maintained. You are the QA team. Keep a fork-readiness note and prefer small, local changes over deep monkey-patching.
• Extension points to prefer: a custom DataSource, a custom field type, and Brick composition. Block-level layout overrides are documented as TODO — treat template override internals as unstable across minor versions.
• Menu visibility is not authorization. Hiding a menu entry or action does not protect the route; enforce it in the controller/firewall yourself.
• Write smoke tests per CRUD using doc/test_your_application.md — at minimum list loads, show loads, edit saves, and one filter applies. Cheap insurance against a bundle that moves fast.