Application Versioning Laravel Package

Product Decisions This Supports

• Release/versioning strategy for Laravel apps. The package owns a version.yaml file plus formatting helpers (getFormatedVersion()) and CLI commands (install, increase), so it directly informs decisions about how version numbers are stored, bumped, and surfaced in a product.
• Build vs. buy for version metadata. Because version storage, bumping, and git-hash enrichment are handled by a small package, PMs can default to adopting it rather than funding in-house tooling — unless versioning needs are unusually bespoke (see below).
• Deployment and environment topology. The new disk support (APP_VERSIONING_DISK, APP_VERSIONING_DISK_PATH) is the key roadmap-relevant capability: version metadata can now live on S3-compatible or other Laravel filesystem disks instead of a local file. This supports decisions about multi-instance/containerized deployments, read-only filesystems, and ephemeral hosts where a local version.yaml is impractical.
• Release traceability and support workflows. Git hash resolution is now resilient on detached HEADs (common in commit-pinned CI deploys) and with refs only in packed-refs (fresh clones, post-git gc). That makes the displayed version string trustworthy in support tickets and incident triage, which underpins decisions about how much build provenance to expose to customers or internal teams.
• Framework upgrade timing. symfony/yaml now allows ^7.1|^8.0 and tests run on Laravel 11/12/13, so this package is no longer a blocker for a Laravel 13 roadmap item. That is a concrete input to upgrade sequencing.
• Operational hardening decisions. Unreadable .git state now degrades to a default instead of throwing, so version display cannot take down a page. This supports a "versioning must never be a runtime failure mode" reliability stance.

Caveats worth carrying into those decisions: this is a small, narrow package (version file I/O, formatting, git hash lookup, two commands). It does not provide semantic-version parsing policy, changelog generation, release orchestration, or artifact promotion — those remain separate product/engineering decisions.

When to Consider This Package

Consider adoption when most of the following hold:

• The product is a Laravel application (11, 12, or 13) and needs a simple, human-readable version identifier surfaced in UI, health endpoints, or php artisan about-style output.
• You want git commit hash appended to the version string for traceability, and your deploys include detached-HEAD checkouts or shallow/packed clones — the 0.2.0 fixes directly address failures in exactly those setups.
• Your runtime is containerized, autoscaled, or read-only, and you need version metadata on a shared/remote filesystem disk rather than a file baked into the image.
• You need write access to the version file (increment command) as part of a release step, and are comfortable granting that through a configured disk.
• You want low integration cost: one config file, one facade/singleton resolution (app(ApplicationVersioning::class) or the ApplicationVersion facade), no breaking changes on upgrade.

Look elsewhere when:

• You need semantic versioning policy enforcement, conventional-commit-driven bumps, changelog/release-note generation, or monorepo multi-package versioning — this package bumps a file, it does not govern release process.
• Version metadata must be written by CI only and never by the app at runtime; a disk-backed writer may be more surface area than you want.
• You require a guaranteed stable public API with long-term support commitments; the singleton-consistency change in 0.2.0 is behavior-preserving but signals the container binding contract is still being normalized.
• Your app is not Laravel or is pinned below Laravel 11 — the dependency constraints target that range.
• You need signed/attested build metadata for compliance rather than a git hash read from .git.

How to Pitch It (Stakeholders)

For executives: This is a small, low-cost dependency that makes "what version is running?" answerable and reliable. The 0.2.0 release removes two practical obstacles to shipping on modern infrastructure and on Laravel 13: version metadata can now live on a configured storage disk instead of a local file (so it works in containerized and horizontally scaled deployments), and the version string stays correct on the commit-pinned deployments our CI produces. It also stops failing when .git is unavailable or unusual, so version display cannot break a page. No breaking changes; upgrade is a config addition at most. Net: reduced release-traceability risk and one fewer blocker on the Laravel 13 upgrade path, at negligible cost.

For engineering: Upgrade is non-breaking. Add disk and disk_path to config/application-versioning.php (or republish) to move version.yaml onto any Laravel filesystem disk; without a disk, behavior is unchanged. getFormatedVersion(), the install command, and the increase command now resolve ApplicationVersioning from the container, so container-level overrides and test fakes behave consistently — prefer app(ApplicationVersioning::class) or the ApplicationVersion facade over new. Git hash resolution now handles detached HEADs and refs found only in packed-refs, and any unreadable .git state falls back to a default rather than throwing (empty $git_hash). Symfony YAML is ^7.1|^8.0; test matrix covers Laravel 11–13. Worth validating: your disk's write permissions if the increment command runs in production, and whether any code relied on constructing the class directly.

Recommended ask: Approve the patch/minor upgrade, add disk configuration if we deploy to ephemeral or read-only filesystems, and treat this as cleared for the Laravel 13 upgrade plan.