Filament App Version Laravel Package

Getting Started

This is a single-purpose Filament add-on: it renders a version chip beside the panel logo, resolves the version from a prioritised list of sources, borrows the panel's primary colour, and is hidden from unauthenticated users by default.

1. Install into an app that already has a Filament panel (v3/v4 — confirm the constraint in composer.json before you commit):

   composer require vaslv/filament-app-version
   

2. Publish the config — the source priority chain lives here, not in the panel provider:

   php artisan vendor:publish --tag="filament-app-version-config"
   

3. Register it on the panel(s) where you want the chip (plugin class name per README; if the package uses a plain service provider + render hook, package discovery may already have done this):

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->id('admin')
           ->plugin(\Vaslv\FilamentAppVersion\FilamentAppVersionPlugin::make());
   }
   

4. Give it something to read. Set APP_VERSION in .env, or add a version key to config/app.php, and confirm the chip appears in the panel header next to the logo while logged in.

Where to look first: the published config file (source order and enabled/disabled flags), then the package's Blade view — that is the file you will actually edit when you want different spacing, a tooltip, or a link to a changelog. The service provider is the third stop; it tells you exactly which PanelsRenderHook is used, which is the thing you need to know if you later want to move or duplicate the chip.

First real use case: stamping the build into staging and production so QA can answer "which deploy am I looking at?" without SSH-ing into the box. Wire it to a CI-written value rather than a hand-maintained constant.

Implementation Patterns

Treat the priority chain as dev/prod divergence, not as redundancy. The natural fit is: git describe --tags first for local work (always accurate, always dirty), a CI-injected env/version file second for deployed artefacts (no .git in the image), composer.json last as a floor. That gives a version in every environment without anyone remembering to bump anything.

Single source of truth from CI. In your build pipeline, derive the version once and write it where the resolver will find it:

- run: echo "APP_VERSION=$(git describe --tags --always)" >> $GITHUB_ENV

Then order the chain so the env source wins in production. Avoid having both a git tag and a composer.json version that drift — the chain will silently pick one and you will debug the wrong one.

Per-panel differentiation. Multi-panel apps (an admin panel and a customer-facing app panel) usually want different answers: the chip is genuinely useful to staff and usually noise for end users. Register the plugin only on the internal panel, or flip the visibility flag per panel rather than globally.

Colour comes from the panel, so do not fight it. The chip inherits whatever ->colors([...]) / brand colour the panel already defines. If you have per-tenant or per-panel theming, the chip follows for free. Only publish and edit the view when you need a distinct treatment (e.g. a red chip when the version contains -dirty or -rc).

Reuse the resolver outside Filament. If the package exposes its version source as a resolvable service (bind it, or call the same config value), surface the identical string in a health endpoint, an /about page, or a Sentry release tag. Two independent version strings in one app is a classic support-ticket generator.

Cache the expensive source. Shelling out to git describe per request is fine locally and unacceptable under load. Either scope the git source to local/testing only, or wrap the result in Cache::remember. php artisan config:cache in your deploy step removes most of the risk.

Gotchas and Tips

• Container builds break the git source silently. Production images have no .git and often no git binary; the resolver falls through to a lower-priority source and you get a stale or blank chip with no error. Verify with the actual deployed artefact, not php artisan serve on your laptop.
• config:cache and env(). If the config file calls env('APP_VERSION') that is fine, but remember the value is frozen at cache time — set the env var before config:cache in the deploy, or the chip shows the previous release.
• The chip "disappearing" is usually auth, not a bug. It is guest-hidden by default. Check the panel's authGuard() and whether you are actually authenticated on that guard; also confirm the render hook fires in the layout you are looking at (some custom topbars bypass it).
• Verify the render hook before you build on it. Read the provider and note the hook constant. If you need the chip somewhere unusual (login page footer, user menu dropdown), do not wait for the package to support it — copy its Blade view into your own renderHook() call.
• Pin the version. Three stars and zero dependents means no community safety net and no guarantee of a fast Filament v4 fix. Use an exact constraint ("vaslv/filament-app-version": "1.0.3") and read the diff before bumping.
• Budget the exit. The whole feature is a version resolver plus a renderHook() returning a <x-filament::badge>. If a Filament upgrade breaks it, forking or inlining it is a 20-minute job — decide up front that you will do that rather than block an upgrade.
• Test the resolution, not the pixel. A small unit test asserting which source wins for each environment config (no .git, env set, env missing) catches every realistic failure; trying to assert the rendered HTML mostly asserts Filament's internals.
• Extension points worth knowing: the config file for source order and visibility, the published Blade view for markup/styling, and the panel's own colour config for the accent — in that order. Everything else requires touching the package.