Filament Balance Header Laravel Package

Getting Started

1. Confirm your stack. This is a Filament panel plugin — it does nothing outside a Filament admin panel. Check the repo's composer.json for the supported filament/filament constraint (last release Jan 2024 points at Filament v3; verify before trying it on v4). If you are not on Filament, stop here.

2. Install and pin.

   composer require lukasccb/filament-balance-header:1.0.3
   

   Pin the exact version. The changelog is a bare compare link, so there is no signal to trust floating constraints on a single-maintainer v1.x package.

3. Register it as a panel plugin (preferred) in your PanelProvider:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugin(BalanceHeaderPlugin::make());
           // ...
   }
   

   The alternative is registering it through a render hook if you only want it on specific pages — see the next section. Confirm the exact plugin class name and fluent method names in src/, because the README is sparse and the package exposes a very small surface.

4. Read these first, in order: src/ for the plugin + render-hook class, the Blade view for the header (that is where label/icon/formatting live), then the release tags to see how little has changed across 1.0.x. There is no meaningful docs site — the source is the documentation.

5. First use case to prove out: a read-only display of the current user's (or tenant's) credit balance in the topbar, backed by a value you already compute elsewhere. Do not start by wiring it to fresh billing logic; wire it to an existing service method so you can validate the display path in isolation.

Implementation Patterns

Plugin registration vs. render hook. Two integration styles, and they are not equivalent:

• Panel plugin — registers globally across the panel; simplest and what most teams want.
• Render hook — target a specific slot (e.g. near the topbar/user menu) so the balance sits where your users expect and coexists cleanly with existing header widgets. Use this when you are also inserting other header elements and need control over ordering.

Feed it from a service, not from the component. Keep the balance calculation in your own application (an action, a BalanceService, a cached lookup) and pass the result into the header. This keeps the display component dumb, makes it testable, and makes replacing the package trivial later.

Resolve per-user / per-tenant, lazily. The header renders on every panel page, so the value fetch runs constantly. Prefer a scoped query or a short-TTL cache keyed by user/tenant over recomputing an aggregate on each request.

Compose, don't collide, with existing header widgets. The package is designed to sit alongside Filament header widgets and actions. If you already render wallet info in a widget, decide which one is canonical — showing the same number twice in the topbar looks like a bug.

Configuration as presentation, not logic. Treat label, icon, and styling options as theme surface. Keep currency formatting and rounding decisions in your formatter (e.g. Number::currency(...) with an explicit locale) so the number shown in the header matches the number shown on the billing page to the cent.

Conditional exposure. Gate registration behind a feature flag or role check in the PanelProvider (or a policy) so the header can be enabled for ops/support only during a pilot, and disabled without a deploy.

Gotchas and Tips

• You own the number. The package renders what you hand it; it has no ledger, no reconciliation, no currency conversion. Display is a convenience surface, not a source of truth. Never let this become the place finance looks for a balance.
• Verify Filament major-version compatibility explicitly. With a Jan 2024 release and no changelog detail, assume v3-era APIs. Test on the exact Filament version you run before rollout.
• Pin and diff before upgrading. v1.0.3 is a patch bump with a compare-link-only note. On a single-maintainer project, do not assume patch semantics — read the diff.
• Render-hook ordering matters. If the header appears in the wrong place or is swallowed by another header element, check which hook slot you registered against and the relative order versus other registered components.
• Per-request query cost. The header renders on every panel page; a naive aggregate query per request is an easy N+1-style perf trap. Cache or precompute, and invalidate on balance-changing events.
• Authorization and leakage. A topbar balance is visible wherever the panel is visible. Make sure the value is scoped to the authenticated user/tenant and does not leak another account's figure through a shared cache key or a stale Livewire payload.
• Empty/zero/error states. Decide up front what to render when there is no balance, when the fetch fails, or when the value is zero — a header showing a silent blank or 0 on error is worse than hiding the component.
• Livewire refresh. A static value passed at render time will not update after a Livewire navigation or an action that changes the balance. If it must be live, wire it to a listener/poll or accept eventual consistency on page load and document that.
• Theming/CSS. Small community components often ship minimal styles; check the Blade view and published assets for conflicts with your panel theme, and confirm the icon set used matches your Filament icon setup.
• Localization and currency. Label text and number formatting are your responsibility — set locale and currency explicitly rather than relying on defaults.
• Maintenance risk / exit cost. Single maintainer, sparse changelog, no security policy. Risk is low because the surface is tiny: worst case, reimplement the same header in roughly a day with a Filament render hook. Record it as a replaceable, non-strategic dependency and keep it out of customer-facing or regulated surfaces.
• Test coverage unknown. Add a thin application-level test that asserts your balance value resolves correctly and the component renders, so a package removal or upgrade is caught immediately.