Event Sourcing Dashboard Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package. It replaces patchlevel/event-sourcing-admin-bundle and provides a browser UI for apps built on patchlevel/event-sourcing. A Laravel developer cannot composer require it into a Laravel app and expect service-provider auto-discovery, Laravel routes, config publishing, or Blade views.

Practical entry points:

• If your Laravel app uses patchlevel/event-sourcing directly: stand up a small Symfony “inspector” app that points at the same event store database. Use the dashboard there, not inside Laravel.
• If you are evaluating the package: read the getting started guide first, then the production usage/security docs. The critical config is patchlevel_event_sourcing_dashboard.enabled: true plus importing the bundle routes under a prefix.
• If you only need aggregate inspection: the dashboard is useful as an ops sidecar, but it does not replace Laravel tooling such as Artisan commands, Telescope, or custom read models.

Minimal Symfony sidecar setup:

composer require patchlevel/event-sourcing-dashboard-bundle
# remove patchlevel/event-sourcing-admin-bundle if present

# config/packages/patchlevel_event_sourcing_dashboard.yaml
patchlevel_event_sourcing_dashboard:
    enabled: true

# config/routes.yaml
patchlevel_event_sourcing_dashboard:
    resource: '@PatchlevelEventSourcingDashboardBundle/config/routes.yaml'
    prefix: /_event-dashboard

Then install assets:

php bin/console assets:install public
# or use Symfony asset mapper

Configure patchlevel/event-sourcing-bundle in the sidecar to use the same event store as your Laravel app. First use case: open /_event-dashboard/store, filter by aggregate ID from a Laravel log entry, then open Inspection to view the aggregate’s events, serialized state, snapshot, and time-travel state.

Implementation Patterns

• Sidecar inspector app: Keep a tiny Symfony app in infra/event-dashboard or a separate repo. Point it at the same MySQL/Postgres event store used by Laravel. Run it locally via Docker Compose alongside Laravel, and in staging behind Symfony security.
• Read-only browsing vs. mutating subscriptions: The Store and Inspection views are the day-to-day value: browse raw events, filter by aggregate, aggregate ID, stream, or event, and time-travel an aggregate to a playhead. Subscription actions such as boot, run, pause, reactivate, setup, rebuild, and remove mutate state, so restrict those routes in shared environments.
• Domain event annotations: Add #[Inspect] to event classes in your shared domain package to improve dashboard rendering with a description, icon, color, and size. This is a PHP attribute, so it can live in code also used by Laravel, but only the dashboard renders it. Keep the domain package free of Symfony dependencies.
• Incident response workflow: Use Laravel logs to capture aggregate IDs, then use the dashboard’s Store filters to locate the stream, Inspection to compare snapshot vs. replayed state, and time travel to reproduce the state at a specific playhead.
• Subscription health checks: Use the Dashboard counts and subscription status breakdown to spot paused or failing subscriptions. Use the Subscriptions view for staging operations, but prefer Laravel commands or your normal deployment tooling for production changes.
• Asset strategy: The bundle self-hosts Inter and JetBrains Mono and makes no external requests, which is good for air-gapped or restricted environments. Use assets:install or the Symfony asset mapper; otherwise the UI will load without styling.
• Route protection pattern: Put the imported route prefix behind Symfony security, VPN, IP allowlist, or basic auth. Do not expose the dashboard prefix publicly just because it is “only a dev tool.”

Gotchas and Tips

• Not Laravel-native: There is no Laravel service provider, no config/patchlevel_event_sourcing_dashboard.php, no Blade views, and no Laravel route registration. Adding it to a Laravel app’s composer.json will not make the dashboard work.
• Migration from the admin bundle: The package name, bundle class, configuration root, and route names changed. Remove the old admin bundle, update bundle registration if not using Flex, update the config root to patchlevel_event_sourcing_dashboard, and re-import the new routes file.
• Disabled by default: If routes return 404, check that patchlevel_event_sourcing_dashboard.enabled is true and that the routes import exists. When disabled, no controllers, routes, or services are registered.
• No built-in access control: The release notes are explicit: the dashboard is intended as a development tool. If used in production, secure the route prefix with Symfony security. Treat subscription mutation actions as privileged operations.
• BC scope is narrow: Route names and paths are covered by the BC policy. Twig templates, template names/blocks/variables, and controller internals are not. Avoid overriding templates or extending controllers if you want smooth upgrades.
• Version constraints matter: PHP 8.2–8.5, patchlevel/event-sourcing ^3.8, patchlevel/event-sourcing-bundle ^3.7, Symfony 5.4/6.4/7/8, and Twig ^3.20. Mismatches usually surface as container compilation errors or missing services.
• Empty dashboard: If counts and events are empty, verify the sidecar’s event-sourcing-bundle connection points to the same database/schema as Laravel, and that the event store tables are the expected ones. Clear the Symfony cache after config changes.
• Debugging routes and services: Use php bin/console debug:router, debug:container, and check the patchlevel_event_sourcing_dashboard config tree. A missing route import or disabled config is the most common cause of a blank/failed dashboard.
• Time travel cost: Replaying large aggregates to an arbitrary playhead can be slow. Use Store filters to narrow down the aggregate first, and avoid treating the dashboard as a high-traffic production monitoring tool.
• #[Inspect] is presentation-only: It customizes description, icon, color, and size in the UI; it does not change event behavior. Keep values simple and validate custom icon/color choices visually.
• Extension points: Prefer route prefix, Symfony security, and the #[Inspect] attribute over patching controllers or overriding Twig templates. Templates and controller internals are explicitly outside the BC promise.