Version Bundle Laravel Package

Technical Evaluation

Architecture fit — poor as delivered, high as a pattern. asgoodasnu/version-bundle is a Symfony bundle: it registers through the Symfony kernel, exposes values via the DI container, and ships a Twig extension. Laravel has no bundle registration step, no Twig, and no equivalent of config/bundles.php. Nothing is autodiscovered via extra.laravel. So the honest framing for the roadmap is: this is not a Laravel dependency, it is a specification for a ~200-line capability we can own outright. What it demonstrates — one authoritative source for version, build number, and commit hash; service-level injection; a view helper; configurable extra metadata — is a genuinely useful micro-capability, and it maps cleanly onto config/version.php, a container-bound Version value object, a Blade directive, and a /version JSON endpoint.

Resolve the scope ambiguity before sizing anything. The repository description describes application build metadata (semver, build, commit). Several surrounding assessments describe entity/record versioning with audit history. These are entirely different features with different storage, concurrency, and compliance implications. A TPM must pin down which one is being evaluated in the first meeting; conflating them will produce the wrong build-vs-buy call.

Integration feasibility — low confidence, but low absolute cost. Zero stars, zero dependents, score 0. For a build-metadata helper that is not disqualifying in the way it would be for a persistence-layer library: there is no write path, no schema, no data migration, and no security surface worth speaking of. The failure mode is a stale version string, not corrupted history. Feasibility of reimplementing the behavior is high; feasibility of adopting the code is low because it drags a second framework's conventions in for one feature.

Technical risk.

• Dependency risk (medium): pulling symfony/* and twig/twig into a Laravel composer.json invites constraint conflicts and pins PHP ranges. An abandoned package becomes a blocker the first time we upgrade Laravel or PHP.
• Value risk (high relative to effort): the capability is trivially reproducible; the dependency buys almost nothing we cannot write in an afternoon.
• Silent-staleness risk (the real one): the version value is only as good as the pipeline that injects it. A default of dev shipping to production is a common and quiet bug.
• Abandonment risk: no release cadence, no triage, no upstream fixes. We own it forever if we take it.

Key questions.

1. Is the actual requirement build metadata, or record-level versioning/history? Confirm in writing.
2. What are the composer.json constraints — PHP, symfony/*, twig/twig? Any conflict with our Laravel/PHP target?
3. Where does the version come from — env var, file, or VCS at build time — and does that survive our containerized/immutable-image build?
4. What does the config surface (DependencyInjection/Configuration.php) expose that we would want to mirror?
5. Is there a tagged release and license permitting a fork/port?
6. Who is the named internal owner for the ported version, and when does it get reviewed?
7. Does the endpoint need to be unauthenticated, cacheable, and safe to expose publicly?

Integration Approach

Stack fit — port, do not require. Recommended shape for a Laravel codebase:

• config/version.php reading APP_VERSION, APP_COMMIT, APP_BUILT_AT from environment.
• A Version value object plus a singleton binding, injectable into any service — same ergonomics as the original's service exposure.
• A Blade directive (e.g. @version) to mirror the Twig integration.
• A cacheable GET /version returning flat JSON, outside auth, for load balancers and the release dashboard.
• Injection from the build pipeline (CI variables or Docker image labels), not from a runtime git call.

Migration path. If the package is already vendored anywhere, treat that as technical debt to retire, not a baseline to extend. If we ever do pull it, vendor/fork it with a named owner and a review date. The default recommendation is a native implementation; the package's value is as a reference design — mine Configuration.php for the metadata fields we should carry.

Compatibility. If a spike is run, verify PHP and symfony/* ranges first. Any constraint that pins the framework or ORM is a hard stop; no benefit here justifies constraining the platform.

Sequencing.

1. Discovery (half day): confirm build-metadata vs. record-versioning; read Configuration.php and the service wiring.
2. Decision memo (half day): recommend native port with a cost estimate; close the "adopt the bundle" option explicitly.
3. Implement (1–2 days): config, value object, endpoint, Blade directive, tests.
4. Pipeline wiring (0.5 day): inject APP_VERSION/APP_COMMIT at build; assert non-dev in production.
5. Surface it: health/release dashboard, deploy annotations, support runbook.

Operational Impact

Maintenance. Negligible for the port — two or three files, standard Laravel, no exotic dependencies. Adopting the bundle would invert that: we would inherit an unmaintained Symfony surface we cannot upgrade and did not write. The port wins on total cost of ownership by a wide margin.

Support. No vendor, no community, zero dependents means zero external documentation and no one to escalate to. Internal docs must be written by whoever does the spike, while the pipeline wiring is still fresh — specifically the "where does the version come from" runbook entry, which is the question support will actually ask.

Scaling. Effectively a non-issue; the endpoint is a static read. Two caveats: keep the payload small and cached (Cache-Control: public, max-age=60), and make sure the value is baked at build time rather than read per request from disk. If the underlying requirement turns out to be record versioning, scaling becomes a real concern (monotonic growth, indexing, retention) and this evaluation should be replaced.

Failure modes (ranked).

1. Silent staleness — the pipeline fails to inject, the default dev or a previous tag ships, and the release dashboard lies during an incident. Mitigation: fail the build if APP_VERSION is unset in production; alert if /version does not match the deployed tag.
2. Caching masks a deploy — an aggressively cached endpoint reports the prior release after rollout. Mitigation: short max-age, cache-bust on deploy, or return the value from the app rather than an edge cache.
3. Missing VCS metadata in the image — .git is absent in the container, so a runtime git describe returns nothing. Mitigation: inject at build.
4. Laravel config:cache bakes env at build time — runtime env changes won't take effect. Document this or the first responder will chase a ghost.

Ramp-up. Very low — any Laravel engineer can own this. That is precisely the argument: the onboarding cost of reverse-engineering a Symfony bundle exceeds the cost of building the capability natively, for a feature whose entire job is to stop version strings being hardcoded in five places.

Recommendation for the decision log: Do not adopt asgoodasnu/version-bundle as a dependency. Extract its configuration surface as a design reference and implement a first-party version-metadata capability (1–2 engineering days) with build-pipeline injection and a /version endpoint. Revisit only if the real requirement is record-level versioning, in which case this package is the wrong candidate entirely and a maintained audit/history library should be evaluated instead.