Admin Bundle Laravel Package

Getting Started

UmbrellaAdmin is a Symfony bundle for building config-driven admin backends for Doctrine entities — in the same space as EasyAdmin, but leaner and more explicit. Expect YAML config plus per-entity PHP configuration classes, wired into a Bootstrap-based Twig layout.

1. Install and register

   composer require umbrella2/admin-bundle
   

   Register the bundle in config/bundles.php (Symfony <5.4 only) and make sure its dependency umbrella2/core-bundle is present — most of the DataTable/Form builder machinery actually lives there.

2. Wire routes — import the bundle's routing under your admin prefix:

   # config/routes/umbrella_admin.yaml
   umbrella_admin:
       resource: '@UmbrellaAdminBundle/Resources/config/routes.yaml'
       prefix: /admin
   

3. Configure config/packages/umbrella_admin.yaml with at minimum layout (Twig template), title, and menu entry point. If you use the built-in user/menu integration, point it at your security provider here.

4. Where to look first: the repo README, then src/Controller/AbstractAdminController.php and src/Admin/ (configuration base classes), then src/Resources/views/ for the layout and block names you can override. The tests/ folder is often the most reliable API reference — read it before the docs.

5. First use case: build a DashboardController extending the bundle's AbstractDashboardController, then a single AbstractAdminController subclass for one entity (e.g. Article) with a matching Configuration class declaring list/show/form fields. Get one CRUD screen rendering end-to-end before touching menus or custom actions — that validates routing, Twig layout, and Doctrine wiring in one shot.

Implementation Patterns

Per-entity Configuration class The dominant pattern is one configuration object per entity, declaring which properties appear in list, show, and form views, plus labels, sortable columns, filters, and searchable fields. Keep these thin: delegate to Symfony Form types for complex form behavior rather than stuffing logic into the config.

Controller as thin glue Your admin controller extends the abstract CRUD controller and overrides only what differs — entity class, configuration, form type, query builder for the list. The base class handles index, show, create, edit, delete and redirect/CSRF plumbing. Custom endpoints live as ordinary controller actions plus a route you reference from the config.

Menus and navigation Menus are assembled through a menu builder service (or YAML tree) and rendered by the layout. Model entries against routes, not URLs, so renames don't break. Use a menu builder service for dynamic entries (counts, role-conditional items) rather than editing YAML; conditional visibility is normally delegated to isGranted checks inside the builder.

Dashboard composition Widgets are typically Twig partials or small controller-rendered fragments slotted into the dashboard layout. Prefer fragment rendering (render(controller(...))) over embedding query logic in the dashboard controller — it keeps each widget independently cacheable and testable.

Actions Global and per-row actions are declared in the configuration with a label, route, and optional confirmation/CSRF settings. Custom bulk actions are the common integration point for "export selected", "bulk archive", etc. — implement them as a POST action that receives the selected IDs, and keep them idempotent.

Template overrides The bundle uses Twig blocks throughout. Override by extending the bundle's layout (@UmbrellaAdmin/layout.html.twig) or by registering a project template path that shadows the bundle view. Do a block-level override rather than copying whole templates — you lose upstream fixes otherwise.

Security Nothing is automatic beyond the firewall you configure. Put access_control on the /admin prefix, require a role on the dashboard controller, and remember custom actions need their own isGranted checks — the base CRUD actions will enforce what you configure, but your bespoke endpoints won't.

Gotchas and Tips

• Small ecosystem — read the source. With near-zero dependents and sparse docs, the bundle source is the documentation. When an API surprises you, vendor/umbrella2/admin-bundle/src is faster than any search.
• Pin versions. These Symfony admin bundles evolve quickly and minor bumps have historically changed configuration signatures and Twig block names. Use exact version constraints in composer.json and review diffs before upgrading.
• Clear cache after config changes. Menu, layout, and route-derived config are cached; a stale var/cache is the #1 cause of "my menu item didn't appear."
• Route collisions. Importing the bundle routes with a broad prefix can clash with your own paths. Keep the admin prefix narrow and namespaced (/admin), and check with bin/console debug:router | grep admin.
• Assets. The layout expects Bootstrap and the bundle's CSS/JS. Either run bin/console assets:install --symlink for bundle assets or pull them through Encore — mixing both is a common source of "no styling" reports.
• Doctrine proxies and custom queries. If you override the list query builder, select the root alias explicitly (->select('e')->from(Entity::class, 'e')) and avoid lazy-loading relations in list columns — N+1 queries on an admin table get ugly fast. Add explicit joins for anything you filter or sort on.
• Debugging entry points. bin/console debug:container umbrella_admin to see the wired services, debug:config umbrella_admin for the resolved configuration, and dump() inside a Configuration class to inspect what the base controller actually receives. The bundle's own tests/ folder shows expected config shapes.
• Extension points to prefer. Configuration classes, Twig blocks, menu builder services, and custom actions cover 90% of needs. Subclassing or copying the abstract controller is the escape hatch of last resort — it makes upstream upgrades painful.
• Filter/search behavior is per-field. A column that renders but doesn't filter usually means searchable/filter wasn't set on that field in the configuration, not that the DataTable is broken.
• Test your admin screens. A smoke test that GETs index/show/create for each admin controller catches broken config and missing routes long before QA does — worth the setup cost given how little community guidance exists.