Admin Page Board Bundle Laravel Package

Getting Started

This is a Symfony2 bundle, not a Laravel package — before anything else, accept that it will not composer require into a Laravel app and work. You will only get value from it inside a Symfony 2.x / early 3.x application that already runs SonataAdminBundle. If you're strictly Laravel, treat this as reference material for how to model dashboards out of reusable blocks (e.g. with a nwidart/laravel-modules-style block registry plus Blade partials), not as a dependency.

Assuming a Symfony2 + Sonata host:

1. Add it to composer.json alongside the matching Sonata stack (sonata-project/admin-bundle, sonata-project/block-bundle).
2. Register in app/AppKernel.php inside the registerBundles() array, after the Sonata bundles:

   new Sonata\AdminBundle\SonataAdminBundle(),
   new Sonata\BlockBundle\SonataBlockBundle(),
   new Suncat\AdminPageBoardBundle\SuncatAdminPageBoardBundle(),
   

3. Import its routing after Sonata's admin routing in app/config/routing.yml.
4. Look first at the bundle's Resources/config/ (services, block definitions) and Resources/views/ — that's where the board/block wiring and templates live. Read the DependencyInjection/Configuration.php to see exactly which config keys the bundle accepts before writing any YAML.
5. First use case: a role-specific landing page — e.g. an "Editor Dashboard" reachable from the Sonata admin menu that renders a grid of blocks (content counts, quick links, recent items) instead of the default global dashboard. Build one board with two or three blocks, verify it renders, then expand.

Implementation Patterns

• Blocks are the unit of reuse. A block is a service tagged with sonata.block (typically sonata.block with an admin context) that returns a BlockContext/Response. Reuse the same block service across the global Sonata dashboard and a custom board — this is the whole point of the bundle: the board is a page shell, the blocks stay portable.
• Define boards declaratively, not in controllers. Keep board definitions in config.yml (or the bundle's convention if it expects a PHP/DI config) so the layout is versionable and reviewable. Avoid hand-building blocks in a controller — you lose caching and the admin context that Sonata's block renderer provides.
• Pair each board with an admin route + menu entry. Register the board's route and add it to a Sonata MenuBuilder group so it appears in the sidebar. Gate it with a ROLE_* check (or Sonata ACL) — boards are often role-specific, and the menu item should be hidden, not just protected at the route.
• One board per audience. Don't overload a single board with a dozen blocks. Create board.editor, board.support, board.finance, each with 3–5 blocks, and switch menu groups by role. This maps cleanly onto how Sonata's own dashboard is configured.
• Templating pattern: keep a thin board template that iterates the configured blocks and delegates each block to its own Twig partial (via the block's TemplateBlockService). Override individual block templates from your app's Resources/ rather than editing the bundle.
• Integration tip: if blocks need data from your entities (counts, recent rows), inject a repository into the block service — not into the board. The board should know nothing about persistence.
• Test the board in isolation by hitting its route with a low-privilege user in dev to confirm the menu gating and block visibility behave as intended before wiring ACL.

Gotchas and Tips

• This is Symfony2-era code and is effectively unmaintained (10 stars, 0 dependents). Expect old Symfony\Component\* APIs, AppKernel, and no PHP 8 / Symfony 4+ support. Audit the code before trusting it in production; be prepared to fork and patch.
• Sonata version drift is the #1 breakage. The sonata.block tag name, BlockContext signature, and AbstractAdmin APIs changed across Sonata 2.x → 3.x → 4.x. Pin exact Sonata versions in composer.json and match the bundle's own composer.json constraints — don't ^-float them.
• Laravel developers: there is no adapter, no service provider, no facade. The concepts (blocks, boards, dashboards) translate; the code does not. Port the pattern, not the package.
• Clear the cache aggressively. Block definitions are compiled into the DI container; changes to block services, tags, or board config won't show up until php app/console cache:clear --env=dev. This is a frequent "my block disappeared" cause.
• Block services must be public and correctly tagged. A missed tag or a private service (common after DI refactors) results in a silently empty board rather than an error. Use container:debug (Symfony2) to confirm the block service is registered with the sonata.block tag.
• Empty board = usually a role/ACL issue, not a rendering issue. Sonata silently filters blocks/menu items the current user can't see. Debug with a super-admin user first, then narrow.
• Template override precedence: app-level app/Resources/SuncatAdminPageBoardBundle/views/... beats the bundle's templates. If your CSS/layout edits aren't appearing, check you're overriding the file the bundle actually renders, not a base Sonata template.
• Extension point: instead of editing the bundle, subclass or decorate the block services and register your own board definitions — this survives a composer update (if you ever take one) and keeps your customizations in src//app/.
• Don't rely on caching benefits for small blocks. Blocks with per-user data should disable block caching in their BlockContext; otherwise a board can leak one user's counts to another.