Dashboard Bundle Laravel Package

Getting Started

Before anything else: this is a Symfony bundle, not a Laravel package. There is no service provider, no config/dashboard.php, and no Blade. If you're a Laravel developer, the mental mapping is:

It is also a satellite of the Kalamu CMS, not a standalone dashboard library. kalamu/dashboard-bundle assumes kalamu/core-bundle (users, security, admin layout, menu system) is installed and configured. Pulling it into a plain Symfony app will give you a renderer with nothing to render.

Version reality check as of v2.0.0: the release is explicitly Symfony 4 + Bootstrap 4. It drops Symfony 2.x support. That is the entire stated delta — a major-version bump for a compatibility adjustment, which usually means the config tree and/or Twig templates moved too. Read the tag diff, not just the notes.

Minimal path:

1. Confirm the host app is a Kalamu install on a Symfony 4.x skeleton with PHP 7.1–7.4. v2.0.0 claims Symfony 4 only — Symfony 5, 6 and PHP 8.x are unverified, not merely "expected to be rough". If you're on Symfony 5+, treat it as an unsupported combination until you've booted it yourself.
2. composer require kalamu/dashboard-bundle:^2.0 — and pin exactly (see Gotchas).
3. Register in config/bundles.php:

   Kalamu\DashboardBundle\KalamuDashboardBundle::class => ['all' => true],
   

4. Look here first, in this order:
   • DependencyInjection/Configuration.php — the authoritative list of every YAML key. Read it before the README; it never lies, the docs might. Do this again on v2.0.0 even if you ran 1.x — this is where a compatibility bump most often hides BC breaks.
   • Resources/config/ — service definitions and the routing file. This tells you the actual route name and path of the dashboard.
   • Resources/views/ — the markup you'll be overriding. v2.0.0 is confirmed Bootstrap 4; if your app is Bootstrap 5 or Tailwind, that is a known restyle cost, not a surprise to discover mid-sprint.
   • Controller/ — usually one thin controller that assembles the view model.
5. bin/console debug:router | grep -i dashboard to find the mounted path, then hit it as an authenticated user.

First real use case: a read-only operations page — a handful of "number + trend" tiles and one or two list panels (recent signups, failed jobs, pending moderation). Resist building anything interactive until you've confirmed the asset and JS story works in your environment.

Implementation Patterns

Config-driven composition. The bundle's reason for existing is that the dashboard is declared, not coded. Expect a config tree roughly along these lines (verify key names against Configuration.php — do not trust a blog post, and re-verify after the 1.x → 2.x jump):

# config/packages/kalamu_dashboard.yaml
kalamu_dashboard:
    title: "Ops"
    columns: 3
    panels:
        - type: text
          title: "Signups today"
          # ...

Treat the YAML as the primary API surface. It diffs well, it's environment-overridable via config/packages/prod/, and it means a content editor can rearrange the dashboard without a deploy — which is usually the actual business requirement behind "configurable dashboard."

Custom panels as services. The scalable pattern for anything non-trivial: implement the bundle's panel/widget interface (check Model/ or Panel/ for the contract), register it as a service, and tag it so the compiler pass collects it. Keep the panel class to two responsibilities — fetch data, return a template + context — and push the query into a repository. Panels are the natural unit of code review here; a 300-line panel class is the failure mode.

Override Twig, don't fork. Symfony's bundle override convention is the extension point you want:

templates/bundles/KalamuDashboardBundle/index.html.twig

Copy from vendor/kalamu/dashboard-bundle/Resources/views/, edit in place. This survives composer update and is far cheaper than a fork. Same trick for the layout block if you need to inherit your app's admin chrome. On v2.0.0, re-copy your overrides rather than assuming last year's copies are still valid — a major bump that touches Bootstrap versions almost always rewrites this markup, and stale overrides silently mask the new structure.

Bridge to your own data. If part of the app is Eloquent or API-backed rather than Doctrine, don't contort the panel abstraction — write a small adapter service that returns plain arrays/DTOs, and let the panel only know the adapter. That keeps the panel testable and keeps the vendor interface at arm's length, which matters a lot for a package with zero dependents.

Menu integration. Kalamu core likely owns the admin menu. Register the dashboard as a menu entry through core's menu service/config rather than hardcoding a link in a template — otherwise the entry disappears the moment someone reorganizes navigation.

Gotchas and Tips

• Adoption risk is still the headline. 3 stars, 0 dependents, a tiny commit history. v2.0.0 is a compatibility patch wearing a major version number — it tells you Symfony 4 is supported, it does not tell you the project is actively maintained. There is no community to answer questions and no upstream to fix a Symfony 6 incompatibility. If you are not already committed to Kalamu, read this bundle as a reference implementation of config-driven dashboards and build the equivalent in your own app — that will cost less than retrofitting this one.
• "Symfony 4" is a ceiling as much as a floor. The release notes name Symfony 4 and only Symfony 4. Do not assume Symfony 5 works because 4 does. Boot the kernel and hit the route before you plan any work on it; that five-minute check is the whole feasibility study.
• Bootstrap 4 is now a stated requirement, not a guess. The markup is Bootstrap 4 class names. On Bootstrap 5 it will mostly render and partly look wrong (form controls, spacing utilities, JS attribute names); on Tailwind it will look broken. Plan the template override pass up front — and if you're on Bootstrap 5, that's a bigger job than 3→4 would have been because the JS API changed, not just the classes.
• Assets probably aren't encapsulated. Older Symfony bundles often assume the host app includes Bootstrap CSS/JS in the base layout. Check Resources/public/ before debugging "why does it look broken" — the answer is usually a missing <link> in your base.html.twig.
• Config tree strictness. Symfony config trees reject unknown keys with a hard failure at cache warmup. When a key from the README throws, run bin/console config:dump-reference kalamu_dashboard and trust that output over the docs. This is the single most likely 1.x → 2.x breakage: a renamed or removed key fails loudly at warmup, which is at least the good failure mode.
• Write the 1.x → 2.x diff down before upgrading an existing install. Bump, then capture config:dump-reference and debug:container --tag=<panel tag> output on both sides and compare. The release notes won't enumerate the renames for you.
• Always bin/console cache:clear after YAML edits in dev if debug is off, or you'll debug a phantom. In dev, Twig template caching also bites when overriding bundle views — rm -rf var/cache/dev/twig is the fast fix, and it's near-mandatory right after taking a new major.
• Debugging order that actually works: debug:config kalamu_dashboard → debug:container --tag=<panel tag> → debug:router → Twig profiler. If the panel doesn't appear, it's almost always an untagged service or a YAML key that silently didn't match a panel type.
• Pin the version exactly. Use "kalamu/dashboard-bundle": "2.0.0" in composer.json and commit composer.lock. A ^1.0 would have let you drift across a major; a ^2.0 in a repo with this little activity buys you nothing but surprise. If you're on Symfony 2/3, note that v2.0.0 drops you — you are staying on 1.x permanently, and that's fine as long as the lock file says so.
• Extension point to prefer: a kernel/request event subscriber or a Twig global for injecting cross-cutting dashboard context (tenant, environment banner), rather than editing vendor templates. Keeps your diff surface at zero when you eventually replace the bundle — and given the maintenance signal, "eventually" is doing real work in that sentence.
• Write one integration test that boots the kernel and asserts the dashboard route returns 200 for an authenticated admin. For a lightly maintained dependency, that single test is your early-warning system for the next Symfony upgrade — and it's the cheapest thing you can do to make the v2.0.0 pin safe.