Version Laravel Package

Getting Started

Start by installing the package as a dev dependency since version reporting is typically used in tooling—not runtime application logic:

composer require --dev sebastian/version

Then create a simple CLI script (e.g., bin/version) to expose your project’s version:

<?php
require __DIR__ . '/../vendor/autoload.php';

use SebastianBergmann\Version;

$version = new Version('1.0.0', __DIR__ . '/..');
echo $version->asString() . PHP_EOL;

Run it with php bin/version. On a Git-tracked repo with tags, it outputs e.g. 1.0.0-17-g00f3408; without Git, it falls back cleanly to 1.0.0-dev if $release is X.Y.

Implementation Patterns

• Artisan Command: Implement a php app:version command in Laravel that injects version info (use a config or .env-backed $release for explicit control).
• Health Checks & API: Expose /internal/version (with authentication!) for deployment verification—append Git commit hash for traceability.
• CI/CD Integration: Dynamically set $release from CI variables (e.g., getenv('CI_COMMIT_TAG') ?: 'X.Y') to ensure version strings reflect the actual build context.
• Testing: Assert expected version formats in integration tests, or tag logs with version to correlate deployments with test runs.
• Configuration-Driven: Store $release in config/version.php (populated by CI) to avoid hardcoding and support rollback-safe versioning.

Gotchas and Tips

• Git Must Be Present & Fully Cloned: git describe fails silently in shallow clones (common in CI). Always run git fetch --depth=10 --tags before version generation if using GitHub/GitLab Actions.
• PHP Version Compatibility: Version 7.0.0+ requires PHP 8.4 (which doesn’t exist yet)—use ^6.0.0 for PHP 8.0–8.3. Verify compatibility via composer show sebastian/version.
• Silent Fallbacks: If no tags exist, or Git metadata is missing, asString() returns $release (e.g., 1.0) or 1.0-dev—log a warning if suffixes like -dev appear in production.
• Avoid Runtime Re-instantiation: Cache the instance (e.g., via Laravel’s singleton or static factory) to prevent repeated Git operations on every request.
• Debugging: Run git describe --tags manually in your repo root to sanity-check expected output—mismatches often stem from detached HEADs or missing annotated tags.
• Subclassing: Extend SebastianBergmann\Version to strip Git metadata for production releases (e.g., return only semantic version) while preserving dev build richness.