Versioning Bundle Laravel Package

Technical Evaluation

Architecture fit — the decisive finding. Despite being catalogued alongside Laravel/PHP packages, shivas/versioning-bundle is a Symfony bundle, not a Laravel package. It ships a Bundle subclass and relies on Symfony's HttpKernel, DependencyInjection, and FrameworkBundle extension/config conventions for registration. Laravel consumes individual Symfony components (Console, HttpFoundation, Process, Finder) but does not ship the bundle/kernel/DI-extension machinery, so this package cannot be composer required and auto-discovered into a Laravel application. There is no Laravel service provider, no facade, no config stub. Any integration would require manually instantiating the bundle's internals against a kernel Laravel does not have.

What the package actually does — and what is portable. The valuable core is small: derive a version string from VCS metadata (Git tags / git describe), expose it via a service, a console command, and a Twig extension. Only the pattern transfers to Laravel; the code does not. The Twig extension is irrelevant to Blade, and the console command is a thin wrapper a TPM could spec in an afternoon.

Integration feasibility for a Laravel stack. Low, and not worth pursuing. A native Laravel implementation — bake APP_VERSION/commit SHA/build timestamp into config at CI build time, expose a /version or /health route, add an app:version Artisan command, and tag log/exception context with the build ID — is roughly half a day of engineering and removes a non-native dependency entirely. That implementation also solves the failure modes this bundle has (see below) rather than inheriting them.

Technical risk if forced onto a Laravel app:

• Framework mismatch is the dominant risk. Community bundles typically test against Symfony kernels only. Symfony 8 support (PR #101) tells us nothing about Laravel compatibility because Laravel is not a test target.
• PHP floor escalation. Symfony 8 requires PHP 8.4+. Pulling 4.2.0 into any dependency graph can force transitive upgrades or fail resolution outright in a Laravel app still on PHP 8.2/8.3.
• Runtime .git dependency. Version resolution typically needs .git or an injected version file at runtime. Containerized and CI-built Laravel artifacts usually lack .git, producing a silent dev-main/unknown fallback in production — the exact moment the version string matters most.
• Maintenance surface. No security exposure (it reads VCS metadata and formats a string), but also no benefit to offset the added dependency.

Key questions to resolve before any scoping:

1. Is this evaluation genuinely for a Laravel service, or is there a Symfony service in the portfolio that spawned it? This is blocking — the answer changes the recommendation completely.
2. If Symfony exists: what is the exact PHP floor and Symfony constraint range in 4.2.0's composer.json, and does it still admit Symfony 6/7 or silently drop them?
3. How would the version be resolved in a .git-less production container — env var, generated file, or build arg?
4. What does "leverage" mean here: adopting the dependency, or harvesting the capability? (For Laravel, only the latter is viable.)
5. Is a build-identifier contract already defined across services, or would adopting this create a second, inconsistent convention?

TPM read: This is a build-vs-buy decision that lands firmly on build for a Laravel portfolio. The capability is real and worth having; the package is the wrong vehicle.

Integration Approach

Stack fit. Mismatch. Treat this repository as reference material and prior art, not as a dependency. The transferable specification is: "every deployed artifact carries an immutable, machine-readable build identifier that is queryable at runtime and surfaces in diagnostics."

If the stack is Laravel (most likely case) — recommended path. Do not attempt installation. Implement the equivalent natively:

• Build time: CI writes APP_VERSION (semver tag), APP_COMMIT (short SHA), and APP_BUILD_TIME into the release artifact's environment or a generated config file — sourced from the same immutable artifact that produced the image.
• Runtime: read those values through config(), never through shelling out to git.
• Surface: a /version route returning JSON, folded into the existing /health endpoint if one exists.
• Diagnostics: attach the build ID to log context, exception reports, and outbound request headers so incident triage starts with "which build?" already answered.
• CLI: a trivial php artisan app:version command mirroring the bundle's console UX.

If the stack is Symfony. Then this package is a reasonable fit: bump the constraint, resolve, clear cache, and verify the version service in staging both with and without .git present. Pin ^4.2 only in services already on Symfony 8; stay on 4.1.x until the surrounding dependency graph catches up, since the Symfony 8 ecosystem of compatible third-party bundles is still thin.

Migration path. None required. Nothing is installed, no prior integration exists, and no data migration is implied. If a Symfony service is onboarded later, 4.2.0 is a fine starting point provided PHP 8.4 is acceptable there.

Compatibility. The 4.2.0 release is a single compatibility-widening change (PR #101) with no API changes or deprecations — a maintenance-green signal for Symfony shops. It carries zero signal about Laravel compatibility, because Laravel is not part of the package's support matrix. Do not let the "PHP package" framing imply otherwise to stakeholders.

Sequencing.

1. Confirm stack ownership (blocking). Determine whether any service in scope runs Symfony. If Laravel-only, close the evaluation immediately.
2. If Laravel-only: file a small internal ticket for the native build-identifier implementation. Agree on what constitutes the version (semver tag, commit SHA, or both) — this is the only genuinely debatable part.
3. If Symfony exists: audit PHP version and Symfony constraint across that service's dependency graph before bumping; verify CI resolves cleanly against 4.2.0; then stage the upgrade.
4. Either way: standardize the /version response shape across services so observability tooling and support runbooks are uniform.

Operational Impact

Maintenance. Very low churn, real bus-factor risk. Single maintainer (shivas), small codebase, infrequent releases (4.1.2 → 4.2.0 is one PR). The code is small enough to fork or vendor if the maintainer disappears — but for a Laravel team, the native implementation eliminates this concern entirely rather than merely mitigating it. Recommend the native path partly because it converts an external dependency into ~100 lines the team owns and understands.

Support. No commercial support, no SLA, community-only via GitHub issues. Acceptable for a diagnostic convenience feature; unacceptable for anything on the critical path. Version exposure should never be a hard dependency of request handling — it should degrade gracefully.

Scaling. Effectively zero cost. Resolution happens once at container boot or on first service access; no per-request I/O beyond a possible one-time git describe subprocess. No scaling considerations in either the Symfony or the Laravel-native variant.

Failure modes to design around (applicable to both paths):

• Missing .git in production containers → version silently resolves to a fallback (dev-main/unknown). Mitigation: inject the version at build time; never rely on runtime VCS introspection in production.
• Shallow CI clones (--depth=1) → tag-less resolution yields a degraded or wrong version. Mitigation: fetch-depth: 0 in the checkout step, or bypass VCS introspection entirely.
• Version drift between the reported string and the deployed artifact → the diagnostic becomes untrustworthy, which is worse than not having it. Mitigation: source the version from the same immutable artifact that produced the image; never recompute it at runtime.
• PHP floor escalation in a mixed monorepo → a Symfony 8 compatibility bump can force transitive upgrades and surface only at install time. Mitigation: lockfile review and staged rollout; do not adopt 4.2.0 outside Symfony 8 services.
• Convention fragmentation → if this bundle is used in Symfony services while Laravel services invent their own scheme, /version responses differ and support tooling breaks. Mitigation: define the response contract once, centrally.

Ramp-up. Negligible for the package. For the recommended Laravel-native alternative, roughly half a day for an engineer familiar with the CI pipeline. The larger effort is organizational, not technical: agreeing on version semantics (semver vs. SHA vs. both) and getting every service to emit the same shape. That alignment work is the same regardless of which implementation is chosen — which is precisely why paying an integration tax for a Symfony bundle makes no sense here.

TPM recommendation. Do not adopt. The 4.2.0 release is a routine forward-compatibility bump (Symfony 8 support, PR #101) with no bearing on a Laravel stack, and the package's Symfony-kernel assumptions make it structurally unusable there. Capture the underlying requirement — immutable build traceability plus a /version or health endpoint — as a small internal task, standardize the response contract across services, and close out this evaluation. Revisit only if a Symfony 8 service enters the portfolio, in which case 4.2.0 becomes a low-risk, high-utility dependency for that service specifically.