Versioning Bundle Laravel Package

Product Decisions This Supports

• Release traceability as a product requirement: The bundle auto-derives the running version from Git tags and surfaces it via Twig, a console command, and DI. That turns "which build is in production?" from a guess into a lookup — useful for support triage, incident postmortems, and rollback verification. A PM can use this to justify a /version or health endpoint as a real, small scope item rather than a nice-to-have.
• Roadmap risk on framework upgrades: 4.2.0 exists solely to add Symfony 8 support (PR #101). That's a maintenance-green signal — the dependency won't become an upgrade blocker through the next Symfony cycle. Relevant if the roadmap includes a Symfony major bump.
• Build vs. buy — and the answer here is "neither, build natively": The capability is small (read VCS metadata, format a string, expose it). Because this is a Symfony bundle, not a Laravel package, it cannot be composer required into a Laravel app without deliberate wrapping work. For a Laravel-first portfolio, the correct decision is to reimplement the pattern natively (~half a day: bake APP_VERSION/commit SHA at build time via CI, expose via /version route and log context, optionally an app:version Artisan command).
• Support/ops workflow scope: High value for internal dashboards, admin panels, and "what version is this customer on?" support flows. Low value for public marketing surfaces. That's a scoping decision, not an engineering one.
• Standardization across a service fleet: If (and only if) the fleet contains Symfony services, adopting one bundle gives a uniform version-exposure contract across them, simplifying observability and incident response.

When to Consider This Package

Adopt when:

• The service is genuinely Symfony (bundle + kernel + DI extension conventions), not Laravel/Slim/plain PHP.
• You need a low-effort version string in templates, services, or a health/version endpoint.
• You're on or moving to Symfony 8 / PHP 8.4+, and want build metadata without owning custom CI plumbing.
• The capability is diagnostic-only and explicitly off the critical path.

Look elsewhere (or build natively) when:

• The stack is Laravel — this is the likely case for this evaluation, and it makes the package a poor fit. The bundle's DI/FrameworkBundle machinery is dead weight; the useful core is ~100 lines.
• You need release orchestration, changelog generation, or semantic-release behavior. This surfaces a version; it does not manage releases.
• You need per-request, multi-tenant, or monorepo-derived version semantics.
• You require supply-chain guarantees (signed releases, SBOMs) — there are none here, and the maintainer is a single individual.

Risks a PM should track before anyone scopes work:

• Stack mismatch is the blocking question. Confirm which services actually run Symfony before committing any engineering time.
• Missing .git in production containers is the classic silent failure — version resolves to dev-main/unknown, quietly eroding trust in the diagnostic.
• Shallow CI clones (--depth=1) produce tag-less, degraded versions; requires fetch-depth: 0.
• Constraint widening to Symfony 8 / PHP 8.4 can force transitive upgrades in a mixed monorepo.
• Bus factor: single maintainer, no SLA, community-only support. Acceptable for a convenience feature; unacceptable on a critical path.

How to Pitch It (Stakeholders)

For executives: This answers a recurring operational question — "exactly which build is running in production?" — which shortens incident triage and makes rollback verification objective rather than assumed. The 4.2.0 release is a routine compatibility bump adding Symfony 8 support; it will not block a future framework upgrade. Cost and risk are near zero. The catch: it's a Symfony bundle, and our stack is Laravel — so the recommendation is to capture the capability as a small internal task (roughly half a day to bake a version identifier at build time and expose it on a health endpoint) rather than add a non-native dependency.

For engineering: shivas/versioning-bundle 4.2.0 adds Symfony 8 compatibility (PR #101) — the only change in the release, with no API changes or deprecations. It's well-suited to Symfony: a Version service, Twig extension, and console command sourced from Git tags with zero configuration. It is not installable into Laravel, since Laravel ships Symfony components but not the bundle/kernel/DI-extension machinery. Action: do not adopt on Laravel services. Instead, implement the equivalent natively — inject APP_VERSION/commit SHA at build time from the same immutable artifact that produces the image, expose it via /version and log headers, and add an app:version command. Revisit the bundle only if a Symfony service enters the portfolio, and even then check the PHP 8.4 floor and confirm the constraint still admits Symfony 6/7 where needed.