Version Laravel Package

Product Decisions This Supports

• Build vs. buy (leaning buy, narrowly): The value isn't the happy path — git describe --tags is a one-liner — it's the tag-precedence rules. The 7.0.1 patch fixes a defect where a tag from an older release series wins after a maintenance branch is merged forward. That's the exact bug we would write ourselves and only discover when a health endpoint reports 6.0.9 on a 7.x build. Buying a maintained edge-case fixer is cheaper than owning that logic.
• Roadmap fit — build-time, not runtime: Scope this as a CI/build-time dependency for version stamping (artifact metadata, php artisan app:version, /internal/version health checks, Sentry/APM release tags, cache-busting keys). It should never sit on a customer request path, which is what makes the risk profile acceptable.
• Use cases unlocked: Multi-series release trains (7.x on main, 6.x maintenance, merged back), cherry-pick-heavy hotfix flows, deployment verification ("is the box running the commit I think it is?"), and log-to-deploy correlation during incident review. If we don't have a second live release series, this is over-engineering.
• Use cases explicitly not supported: Changelog generation, monorepo per-package versioning, release orchestration, or semantic-version bumping. Do not let this get scoped into "we'll build our release tooling on it."
• Diligence items before sign-off (PM-owned, not engineer-owned):
  • PHP line coupling is a roadmap constraint. v7.x targets PHP 8.4, v6.x → 8.3, v5.x → 8.2, v4.x → 8.1. Every PHP upgrade forces a major bump here. Cheap, but it must be in the upgrade runbook, and it means adopters must pin the correct major for their runtime rather than composer require latest.
  • Metadata in this dataset is internally inconsistent — a future-dated release, a zero dependent count against 6.5k stars, and a source claiming an unsatisfiable PHP constraint. Treat the dependent count as unreliable rather than as evidence of abandonment, but read composer.json and the actual tag list ourselves before we standardize.
  • Adoption is transitively guaranteed anyway. It arrives with PHPUnit; the real decision is whether we depend on it directly in application/CI code, which is a much smaller commitment.

When to Consider This Package

Adopt when:

• You need a version string inside PHP (artisan command, health endpoint, exception payload) rather than just in the pipeline, and you maintain more than one release series or regularly merge release branches forward.
• Your workflow is already tag-driven — annotated tags on release commits, tags present on the default branch.
• You want a two-line API (new Version('X.Y.Z', __DIR__) → asString()) over a hand-rolled tag parser.
• You can pin to ^7.0.1 or later on the matching PHP line, and your CI does a full or deepened clone (git fetch --depth=10 --tags) — shallow clones make git describe fail silently and you'll ship -dev versions without noticing.

Look elsewhere when:

• You only need the version in CI. A git describe --tags step writing a generated file (or config/version.php) is zero dependencies and zero PHP-line coupling. This is our fallback and it should be built regardless — it's the pilot's exit criterion.
• You need the version of an installed package at runtime. Composer's installed-versions data already answers that; don't shell out to Git.
• You're single-series. One main, one release line, no maintenance branches — the tag-precedence fix buys you nothing.
• You need release management, not version resolution. Different product.
• The manifest doesn't confirm a PHP constraint you can run, or the next release is another 12+ months out. One targeted patch is a maintenance signal, not a health guarantee; reassess on cadence, not on stars.

How to Pitch It (Stakeholders)

To executives: "A small, build-time-only dependency that turns our Git tags into a trustworthy version string. The current patch fixes a specific bug we'd likely have hit ourselves — after merging a maintenance branch into main, older releases reported the maintenance version instead of the current one. Someone is running this in exactly our branching model and fixed it, which is the maintenance signal we want. Blast radius is contained: it runs in the pipeline and internal tooling, never in customer-facing request paths, so a bad release breaks a build rather than production. Cost of adoption is a Composer line and a pinned major."

To engineering: "Pilot ^7.0.1 on the release branches for one cycle, behind a config/version.php value that CI populates from CI_COMMIT_TAG. Guardrails: full clone with tags fetched in CI, assert the reported major matches the branch's series, and warn loudly if -dev shows up in a production build. We build the git describe fallback in parallel — if the tool doesn't earn its keep in one cycle, we drop it with no rework."

Framing correction to carry into the room: an earlier review of this package was based on unverified metadata — an unsupported-constraint claim and a release date that don't reconcile with the published line. We're re-baselining on the actual manifest and tag history before final sign-off, and I'd rather flag that now than have it surface after we've standardized.