Badger Laravel Package

Technical Evaluation

Architecture fit cachethq/badger is a small, single-purpose presentation-layer package: it renders shields.io-style SVG badges from within a Laravel application. It introduces no persistence, no queue or external service dependency, and no meaningful coupling to domain code, so it slots in as a view/utility concern rather than an architectural commitment. That makes it low-consequence to adopt and equally low-consequence to remove. It is a natural fit where a TPM would otherwise stand up image-generation calls to shields.io — it removes a third-party runtime dependency from status pages, READMEs and dashboards, at the cost of owning the rendering.

Integration feasibility Straightforward: Composer install, package auto-discovery, optional config/view publishing, and rendering via Blade or a route. v5.0.0 explicitly targets Laravel 12 and 13, which aligns the package with the framework versions we would be building on for the next 18–24 months. The new for-the-badge style is additive and cosmetic, with no schema or API surface implications beyond style selection. The automated release pipeline (tag → GitHub release + changelog) is a governance improvement: it gives us traceable, reproducible version boundaries instead of hand-cut tags, which is what makes a pinned dependency defensible in a review.

Technical risk Overall low, with three caveats a TPM should record:

1. PHP 8.2+ floor. This is a hard runtime constraint. Any service still on PHP 8.1 cannot take v5 and must remain on the 4.x branch. This is a deployment gate, not a code gate, and should be verified against the platform image before commitment.
2. Laravel 11 is conspicuously absent. The release notes claim support for 12 and 13 only, and direct Laravel 8–10 users to 4.x. Laravel 11 sits in the gap with no stated position. It very likely works under the same constraints, but "likely works" is not a support claim. Any property on Laravel 11 needs a spike before we treat this as a drop-in.
3. The changelog skips v4.0.0. The full-changelog link compares v3.0.0...v5.0.0, so breaking changes introduced in the 4.0 major are not enumerated here. We are being asked to accept a two-major jump with visibility into only the most recent one. That is the single largest unknown in this release.

Key questions

• Is Laravel 11 intentionally unsupported, or merely untested? What is the maintainer's stated support matrix?
• What broke in v4.0.0, and is there a documented upgrade guide from 3.x?
• Does the for-the-badge style require re-publishing config or views, or is it selectable at call time?
• Are rendered badges cacheable (deterministic output, no per-request state)? This determines whether we can put them behind a CDN.
• What is the bus factor and release cadence for the package? Automated releases improve hygiene but do not by themselves indicate maintainer depth.
• Do we rely on the SVG output as a contract (visual regression tests, snapshot assertions)? If so, a style change becomes a test-breaking change.

Integration Approach

Stack fit Adopt only on services running PHP 8.2+ and Laravel 12 or 13. For anything on PHP 8.1, or Laravel 10/11, pin the 4.x line and treat the badge-rendering capability as a known-frozen dependency. Treat PHP 8.4 compatibility (explicit nullable parameters) as a forward-looking positive — it removes a known deprecation trap if we move to 8.4 during this cycle.

Migration path For a 3.x consumer, do not jump blindly. Sequence: confirm PHP runtime is 8.2+ (ideally 8.4-ready) → confirm framework is 12/13 → read the 4.0 changelog and upgrade guide → bump to 5.x on a branch → re-publish config and views and diff against the current published copies → visually diff rendered badge output before and after. If the 4.x changelog is unavailable or unclear, upgrade to 4.x first, validate, then move to 5.x — two smaller steps with a known-good waypoint beat one opaque leap.

Compatibility The package is additive in this release: new style, new framework support, no removals announced. The compatibility risk is entirely version-floor risk (PHP and Laravel), not behavioural. The Pest 3/4 and Testbench 10/11 upgrades are internal to the package's own test suite and do not affect consumers, though they do indicate the package is being actively maintained against the current testing stack — a mild positive signal for longevity.

Sequencing

1. Runtime and framework baseline check (PHP ≥ 8.2, Laravel 12/13) — blocks or unblocks everything else.
2. Spike on Laravel 11 if any property sits there; do not assume.
3. Upgrade on a branch with published-asset diff and SVG output diff.
4. Add or confirm a small snapshot test around rendered badge output so future style changes surface as test failures rather than silent visual drift.
5. Adopt the for-the-badge style opportunistically — it is cosmetic and can ship independently of the version bump.

Operational Impact

Maintenance Low ongoing cost. The package is small, so forking or vendoring remains a credible fallback if maintenance stalls — a meaningful risk mitigant for a dependency of this size. Automated releases and changelog generation reduce the "what changed and when" overhead that normally consumes TPM time during upgrade reviews. The main recurring task is tracking the PHP floor: each major will likely raise it, so budget a review at every Laravel major.

Support Community open-source under Cachet HQ, no commercial SLA. Acceptable for a presentation-layer utility; not acceptable for anything on a critical rendering path without a fork-and-own contingency written down. Escalation path is upstream issues, with our own fork as the pragmatic backstop.

Scaling SVG generation is CPU-light and stateless, so throughput is a non-issue at our volumes. The real scaling consideration is request volume: badges embedded in READMEs and status pages get hit far more often than the pages they decorate, and often by unauthenticated traffic. Serve them from a route that responds with explicit cache headers, or pre-render and serve statically. Confirm output is deterministic before caching — if any badge embeds a timestamp or request-derived value, naive caching will produce wrong results.

Failure modes

• Deploy-time fatal: PHP version below 8.2 on the target image. Caught by a pre-deploy version assertion, not by tests.
• Silent visual regression: badge style or SVG markup changes across a major, breaking snapshot tests or degrading embedded badges. Caught by rendering diff.
• Published-asset drift: config or views published under an older major shadowing new defaults. Caught by re-publish and diff, not by the upgrade itself.
• Route exposure: a publicly reachable badge endpoint becomes an unauthenticated rendering surface. Scope the route and cache it deliberately.
• Support-matrix surprise: assuming Laravel 11 is fine because it works locally, then hitting an untested edge on an upgrade. Resolved by the spike in step 2.

Ramp-up Hours, not days. A single engineer can complete the upgrade and validation. The for-the-badge addition requires no learning curve — it is a style flag. The only knowledge worth capturing is the version-floor matrix (which PHP/Laravel pairs get which package major) and the snapshot-test convention, both of which fit in a short runbook entry.