Dashboard Bundle Laravel Package

Getting Started

First, the framework reality check: this is a Symfony bundle, not a Laravel package. There is no service provider, no facade, no config/dashboard.php to publish. If you are working strictly inside a Laravel app, there is no supported integration path — the only realistic ways to use it are to run it inside a Symfony application (or a Symfony kernel embedded alongside Laravel, which is almost never worth the cost). Treat the rest of this document as guidance for the case where you inherit or maintain a Sonata-based Symfony admin and need to understand the dashboard layer.

Prerequisites

composer require sonata-project/dashboard-bundle

• PHP 7.3–8.0 era, Symfony 4.4/5.x
• sonata-project/block-bundle (mandatory — the dashboard is a thin orchestrator over blocks)
• sonata-project/admin-bundle (optional, but this is where the dashboard is actually viewed)
• Twig, and a working Sonata admin layout

Register the bundle

// config/bundles.php
return [
    Sonata\BlockBundle\SonataBlockBundle::class => ['all' => true],
    Sonata\DashboardBundle\SonataDashboardBundle::class => ['all' => true],
];

Where to look first

1. DependencyInjection/Configuration.php in the bundle — this is the authoritative list of dashboard options. Docs lag behind it.
2. Resources/config/*.xml — the block service definitions and the dashboard controller wiring.
3. Your app's config/packages/sonata_block.yaml — block contexts are what actually gate whether a block can render on the dashboard.
4. The routing import, then the controller that renders the dashboard page.

First use case: render a single block on the dashboard page so you can confirm the block pipeline works end to end before layering on real widgets.

# config/packages/sonata_dashboard.yaml
sonata_dashboard:
    blocks:
        - position: top
          type: sonata.block.service.text
          settings:
              content: "<h3>Welcome</h3>"

Then hit the dashboard route (typically under your admin prefix, e.g. /admin/dashboard). If you see the block, the container wiring, block manager, and Twig layout are all correct.

Implementation Patterns

YAML-configured dashboards. The intended workflow is declarative: each entry is a position (top, left, center, right, bottom), a type (a block service alias registered in sonata_block), and a settings map passed straight through to the block. Positions are just Twig layout slots — there is no grid system, so visual structure comes from your template overriding the dashboard layout.

Custom block services. Real dashboards need real data. The pattern is: extend AbstractBlockService (or implement BlockServiceInterface), declare execute() returning a BlockResponse with a TemplateReference and a settings array, then tag the service sonata.block with an alias matching the type you reference in YAML.

class PendingOrdersBlock extends AbstractBlockService
{
    public function execute(BlockContextInterface $context, ?Response $response = null): Response
    {
        return $this->renderResponse('dashboard/blocks/pending_orders.html.twig', [
            'block'    => $context->getBlock(),
            'settings' => $context->getSettings(),
            'orders'   => $this->repository->findPending(),
        ], $response);
    }
}

app.block.pending_orders:
    class: App\Block\PendingOrdersBlock
    tags:
        - { name: sonata.block }

Role-scoped visibility. The most common day-to-day requirement is "this widget only for finance." Use the roles setting on the block config (or a settings override inside the block itself) rather than branching in Twig — it keeps the permission model in one place and lets you audit it with a grep.

Caching is per-block, not per-dashboard. Every block gets its own cache key and TTL through the block context. For expensive aggregates, set an explicit ttl/cache setting in the block config and let the block bundle handle invalidation. Never cache inside your block service and set a block TTL — you get two layers fighting each other and stale data is impossible to reason about.

Integration with SonataAdmin. In SonataAdminBundle 4.x the dashboard was absorbed into the admin bundle itself. If you are on 4.x, do not install this bundle — use sonata_admin.dashboard config instead. If you are on a 3.x admin, this bundle is the correct layer and your block services are reused unchanged during migration, which is the one genuinely useful thing about the split.

Programmatic rendering. For custom pages that are not the admin dashboard, inject the block renderer / block service manager and render a block by type directly. This is the escape hatch when a controller needs a dashboard-style widget outside the dashboard route.

Gotchas and Tips

This bundle is archived and has been folded into SonataAdminBundle. Last release 2021, no security maintenance. On any new Symfony work, configure the dashboard in sonata_admin and skip this package entirely. Only pin it if you are pinned to an older admin version and cannot move.

Framework mismatch is the headline. Everything here assumes the Symfony DI container, sonata_block contexts, and Twig. There is no Laravel bridge, no community port, and 0 dependents means no one has paved the road for you. Do not budget time for "adapting it" — budget time for reimplementing the dashboard concept natively.

Block contexts are the #1 source of "block not found". A block service can be perfectly registered and still fail on the dashboard if the block type is not allowed in the dashboard context:

sonata_block:
    blocks:
        app.block.pending_orders:
            contexts: [dashboard]

A block with no contexts key is allowed everywhere; a block with contexts: [admin] will silently fail on the dashboard. Check this first when a widget renders blank or the page throws.

Settings are passed through verbatim. There is no schema validation on per-block settings. A typo in a settings key does not error — the block just gets null and renders oddly. Keep block settings keys documented next to your YAML, or write a custom OptionsResolver in setDefaultSettings() so a bad key fails loudly.

Cache invalidation after block changes. Block service definitions and their tags are compiled into the container. After adding a block service, cache:clear in dev is not enough if you are debugging a stale container in prod — the container needs rebuilding. This eats an hour regularly.

Template resolution is relative to the block service's context. TemplateReference names in execute() are resolved against Twig's normal loader, so overriding a vendor block template means copying it into templates/bundles/... at the right path, not just anywhere in templates/. Get the path wrong and Twig falls back to the vendor template without a warning.

Public services / deprecations. Later Symfony versions deprecate non-public services and the block manager needs to reach your block. If a block service works in dev but fails in prod, it is almost always service visibility or a missing tag, not a logic bug.

Extension points worth knowing: BlockContextInterface settings for per-instance configuration, the block service setDefaultSettings() for validation, and overriding the dashboard Twig layout for anything visual. There is no event system for "dashboard built" — if you need dynamic block ordering, you do it by overriding the template or building the block list in a custom controller.