Backend Dashboard Bundle Laravel Package

Getting Started

Know what you're adopting first: modera/backend-dashboard-bundle is a Symfony bundle, not a Laravel package. It is the Ext JS–based backend "desktop" for Modera's MJR stack (it sits alongside mjr/core-bundle, modera/security-bundle, and friends). Last tagged release was June 2016 and the repo is archived, so treat it as a reference architecture or a legacy-maintenance dependency, not a live install.

Minimal steps for a legacy Symfony 2.x app that already uses MJR:

1. composer require modera/backend-dashboard-bundle — then immediately pin the exact version. Do not let a composer update float this, since its Symfony/Doctrine constraints are pinned to the 2.x era and will conflict with anything modern.
2. Register the bundle in AppKernel::registerBundles() after the MJR core and security bundles; the dashboard reads from their registries.
3. Run the bundle's Doctrine migrations (app/console doctrine:migrations:migrate) — the dashboard persists per-user dashboard configuration.
4. Clear and warm the cache; the item registry is compiled.

Where to look first, in this order:

• Dashboard/ — the item contract (DashboardItemInterface / AbstractDashboardItem) and the provider/registry classes. This is the surface you actually code against.
• DependencyInjection/*Extension.php and Resources/config/services.xml — the config tree and, critically, the service tag name you must apply to your own widgets.
• Contributions/ — how the bundle feeds items, menu entries, and permissions into MJR.
• Resources/public/js — the Ext JS base class your front-end widget extends.

First use case: add a "This week's signups" widget to the backend home screen, visible only to users holding a given role, backed by a route that returns the count. That exercises all three layers you'll touch daily: PHP provider → service tag → JS widget class.

Implementation Patterns

The two-layer widget pattern. Every dashboard item is a PHP/JS pair:

• PHP: a service implementing the item interface (usually by extending AbstractDashboardItem), exposing an id, a label, an icon, a permission/role requirement, and the route or content it renders. Tag it with the tag name found in services.xml and give it a priority — that's what controls ordering.
• JS: a class extending the bundle's base dashboard item component, registered so the desktop knows how to instantiate it. This registration typically lives in a contributions class rather than a hand-edited manifest.

Prefer contributions over config edits. MJR's model is that bundles contribute to registries (Contributions/ classes) rather than editing vendor YAML. Follow it: add menu entries, permission definitions, and item registrations as contribution services so ordering is deterministic and nothing is lost on a cache rebuild.

Per-user state is the bundle's job, not yours. Don't build your own "which widgets does this user see" table — the bundle already persists dashboard layout/settings per user. Your item just declares defaults; the user customizes on top.

Integration tips that pay off daily:

• Back widgets with a normal controller route and return JSON; the JS side does the fetch. Keeps the widget testable with curl and swappable later.
• Gate every item with a permission check at both layers — hiding the JS tile is cosmetic, the route must also refuse.
• Keep widgets read-only and cheap. The dashboard is the landing page: one slow widget stalls the whole screen. Cache aggregate queries and give them an explicit TTL.
• Reuse a single translation domain per bundle for item labels; the desktop renders them from the server side, so untranslated labels are visible immediately.

Gotchas and Tips

• Archived and unmaintained. No security fixes, no PHP 8 / Symfony 6 compatibility. If you're inheriting it, budget for a fork; if you're evaluating it fresh, budget for a rewrite.
• It is not Laravel, and it does not port. There's no service provider, no Eloquent, no Blade, no config/*.php. The equivalents are bundle registration, Doctrine entities, Twig/Ext JS, and a semantic config tree. A Laravel "port" means re-implementing the registry and per-user settings from scratch — usually cheaper than translating this code.
• Silent tag failures. A misspelled service tag or a missing public: true in an old Symfony version means your widget simply never appears, with no error. Debug with app/console debug:container --tag=<tag> and confirm your service is in the compiled container before you touch JS.
• Caching is aggressive. The item registry is compiled into the container. After adding or reordering items, cache:clear (and in dev, cache:warmup) before concluding it's broken.
• Asset pipeline is of its era. The JS contributions are compiled into the backend's asset bundle — adding a widget class without rebuilding that bundle gives you a 404 on the script and an empty tile. Check whether the repo uses Bower/npm-of-2016 and whether your build still runs.
• Migrations and mapping drift. The bundle ships Doctrine entities; if you fork it or change the settings schema, keep the migration path intact or per-user dashboards will break on deploy.
• Extension points to lean on: MJR semantic config + Extension classes for defaults, contributions for registrations, and the item provider interface for anything dynamic (e.g., items only valid in certain contexts). These are the seams that let you avoid forking the bundle — use them, because a fork of an archived bundle is a permanent tax.