Filament App Version Laravel Package

Technical Evaluation

What it is: A Filament panel plugin that renders the application version as a chip adjacent to the panel logo, resolving the version string from a prioritised chain of sources (e.g. explicit config → APP_VERSION env → composer.json → git tag → package.json), inheriting the panel's own primary colour palette, and gated behind authentication by default.

Architecture fit

• Purely presentational and additive. It touches no models, migrations, routes, middleware, or queues — the integration surface is a single PanelProvider registration plus an optional config file.
• Correctly scoped as a Filament plugin rather than a service provider, so it composes with multi-panel setups and per-panel ->plugin() registration.
• The priority-chain resolver is the only piece with real logic; everything else is a Blade view and a small plugin class. That is the right shape for this feature.

Integration feasibility

• Low effort: composer require vaslv/filament-app-version, add the plugin to the relevant panel(s), optionally publish config to pin the source order. Estimate well under a day including verification.
• The "hidden from guests by default" default aligns with the safe behaviour we want; the risk is the inverse — a team member flipping it visible on a public-facing panel and disclosing an exact build identifier. That is information disclosure of low severity but non-zero (lets an attacker correlate to known CVEs in that release).

Technical risk

• Adoption risk is the dominant risk, not code risk. 3 stars, 0 dependents, single author. Treat it as effectively unmaintained until proven otherwise.
• Filament major-version coupling. Filament v4 changed plugin and render-hook conventions; small packages frequently lag a major release. Verify the composer.json constraint explicitly rather than trusting the README.
• Blast radius is contained. If the package breaks or is abandoned, the fallback is a ~40-line custom Blade component plus a render hook. This is the rare case where vendor risk is genuinely cheap to absorb.
• Filesystem reads at render time. If the resolver stat/parses composer.json or shells out to git on each panel page load, that is per-request I/O on every authenticated page. Confirm caching or add it.
• Production metadata assumptions. Git-tag resolution silently fails in most deploy pipelines (no .git in the artefact). The practical chain in production will usually be config → env, which means the real requirement is that our release pipeline injects APP_VERSION — a process dependency, not a package feature.

Key questions to resolve before adoption

1. Which Filament majors are supported, and what is the constraint on filament/filament?
2. Does it register via render hook or publish/override a panel view? The latter is fragile against custom themes and Filament upgrades.
3. Is the resolved version string cached, and can the cache key/TTL be configured?
4. What is the exact priority order, and what happens when every source misses — blank chip, exception, or unknown?
5. Does a failure in resolution bubble up and break panel rendering, or is it caught?
6. Any i18n for the label, and does the chip meet contrast/accessibility expectations against arbitrary panel palettes?
7. Is the guest gate configurable per panel, and what is the default for unauthenticated API/SPA contexts?

Integration Approach

Stack fit

• Natural fit for any Laravel + Filament admin panel already registered through a PanelProvider. Where we run multiple panels (e.g. internal ops vs. a customer-facing portal), register selectively — internal-only is the sensible default.
• Complements, rather than duplicates, our CI/release metadata: it surfaces a value our pipeline already knows.

Migration path

• No migration required; nothing to backfill. It is greenfield display.
• The relevant migration is process: introduce a build-time APP_VERSION (semver + short SHA) into the deploy configuration so the resolver has a reliable, deterministic source in every environment, including container images with no .git and no dev dependencies installed.

Compatibility

• Pin the Filament major in our root composer.json and lock the package to that same major before merging. Do not allow a floating constraint on a package with one maintainer.
• Verify behaviour under our panel theme/custom branding — the chip claims to use panel colours, which is only meaningfully testable against a non-default palette.
• Check interaction with any existing logo override or custom sidebar header partial.

Sequencing

1. Spike (0.5 day): install on a branch against our exact Filament version, exercise all resolution sources, test with .git removed and APP_VERSION unset.
2. Vendor decision gate: if the spike surfaces any friction — or simply as the default given the adoption profile — copy the plugin into app/Filament/Plugins/ under our licence obligations (MIT permits, retain attribution) and own it. Forking is cheaper than tracking a one-maintainer dependency.
3. Pipeline work: emit APP_VERSION into env/config at build time; make it the first-priority source so behaviour is identical across local, staging, and production.
4. Register on the internal panel only, behind auth, with a config default we control.
5. Verify in staging, including a deliberately broken source to confirm graceful degradation.
6. Roll out to remaining panels if there is demand.

Operational Impact

Maintenance

• Steady-state cost is near zero if vendored; the feature is inert. The real maintenance item is the upstream: with 3 stars and 0 dependents, expect no timely fix for a Filament v5 break. Budget the fork.
• Attribution and MIT notice retention if we vendor — a legal-hygiene checkbox, not a blocker.

Support

• Community-only, single maintainer, no SLA, no security policy. Escalation path is "read the source, patch it ourselves."
• Document the internal owner explicitly; an unowned vendored snippet becomes archaeology in 18 months.

Scaling

• Negligible. The chip is static markup. The only scaling concern is the resolver: ensure the version is resolved once and cached (config/opcache/Cache::rememberForever) so it is not re-derived per request, and never shell out to git on a hot path.

Failure modes

• Resolver exception breaks panel render. Highest-severity mode: a missing or unreadable composer.json, a permissions change, or a malformed config takes down every authenticated page. Must confirm the resolver is defensive; if not, wrap it.
• Silent unknown chip. Low severity but erodes trust in the signal — the indicator is only useful if it is always correct. Alert on it.
• Stale version. Cached value not busted on deploy, showing the previous release — actively misleading during incident triage. Cache key must include the artefact/deploy identity, or cache must be cleared as a deploy step.
• Accidental guest exposure. Version disclosed on a public panel. Default is safe; guard against configuration drift in review.
• Upgrade break. A Filament major bump removes the render hook and the chip vanishes silently — cosmetic, obvious in QA, not dangerous.

Ramp-up

• Trivial for any engineer familiar with Filament — a few minutes to read, under an hour to fork and own. No specialised knowledge required.
• The only non-obvious knowledge is the release-pipeline coupling (APP_VERSION propagation), which belongs to platform/DevOps rather than the feature team.

TPM verdict The engineering cost is genuinely small and the risk is contained because the fallback is a few dozen lines we control. The honest framing for stakeholders is that we are not adopting a dependency so much as borrowing a pattern: vendor it, own it, wire APP_VERSION into the pipeline as the authoritative source, and treat the upstream as reference material. Do not add it to the dependency inventory as a supported third-party component.