Version Laravel Package

Getting Started

1. Install the package

   composer require pragmarx/version
   

2. Publish the config

   php artisan vendor:publish --provider="PragmaRX\Version\Package\ServiceProvider"
   

   This drops a config/version.yml file — that YAML file, not your database, is the source of truth for the version number. Open it first; it contains the current major/minor/patch values and the format template used to render them.

3. Confirm registration On Laravel 5.5+ the service provider and Version facade are auto-discovered. On older apps, add PragmaRX\Version\Package\ServiceProvider::class to config/app.php and register the facade alias (e.g. 'Version' => PragmaRX\Version\Package\Facade::class).

4. First use case — expose the version on a health/status route:

   Route::get('/version', fn () => ['version' => Version::get()]);
   

   Then try Version::major(), Version::minor(), Version::patch(), and a formatted call such as Version::format('compact') or Version::full() to see what your config's format templates render.

Start by reading config/version.yml and the package's README together — the format strings in the config map directly to the facade methods, and that mapping is where most of the day-to-day value lives.

Implementation Patterns

Bump on release, not at runtime. The natural workflow is to have your release script or CI job bump the version before tagging:

php artisan version:increment patch   # verify exact command in the README
git tag "v$(php artisan tinker --execute='echo Version::get();')"

Even if the artisan increment command isn't what you need, wrapping Version::incrementPatch() / incrementMinor() / Version::set('1.4.2') in a small custom command keeps bump logic in one place.

Cache-busting assets and templates. Inject the version into a Blade layout or a generated version.json so frontends can bust caches:

// Blade
<script>window.APP_VERSION = "{{ Version::get() }}";</script>

Health and diagnostics endpoints. Return Version::get() alongside commit/build info so support can correlate bug reports with deployed code. This is the highest-value, lowest-risk integration.

Log enrichment / headers. Add the version to outgoing HTTP headers (X-App-Version) or to log context via Monolog tap so production logs are version-stamped.

Consistent formatting at the boundary. Keep the raw major.minor.patch internally and format only at the presentation layer (API response, UI footer). Don't scatter different formats across controllers.

Deployment metadata. If your config pulls a git commit or build number, surface it in an /about page or a Sentry release field so errors map to a deploy.

Wrap it. Put the package behind a tiny internal service (AppVersion) that returns a DTO (major, minor, patch, string, build). That gives you a seam to swap the package, mock in tests, and add SemVer parsing later.

Gotchas and Tips

• YAML, not PHP. The config is .yml, so it isn't covered by config:cache the way PHP configs are, but it also isn't validated by PHP's syntax checker. A stray tab or bad indent yields confusing parse errors at boot. Use an editor with YAML linting.
• Write permissions. If you call increment methods from a web request (don't — but people do), the PHP user must be able to write config/version.yml. In containers this is often read-only; prefer CI-time bumps.
• Immutability in containers. If version.yml is baked into an image, runtime increments are lost on redeploy and can cause dirty working trees. Treat the file as build input, not runtime state.
• config:cache staleness. If you also cache config or read version in a long-running worker (Octane, queue workers), the value is captured at boot. Restart workers after a bump, and don't expect a live file edit to be picked up mid-process.
• No SemVer guarantees. The package stores and formats numbers; it does not enforce SemVer rules, handle pre-release tags, or manage git tags. Add that logic yourself if you need 1.2.3-rc.1.
• Git/build features need the git binary. If your config pulls commit hashes or build numbers, ensure git is installed in the build image and that the repo is present (some CI checkout modes use shallow/no-git copies).
• Low maintenance velocity. At ~590 stars and minimal dependents, expect sparse updates. Pin the version in composer.json, check Laravel compatibility on major upgrades, and keep the wrapper so you can replace it with a one-liner (composer.json version field or a Blade constant) if it stalls.
• Don't duplicate version sources. Pick one of: this package, a VERSION file, or composer.json. Two sources will drift, and the drift is always discovered during an incident.
• Extension points: the format templates in version.yml and the facade bindings are the two hooks worth customizing. For anything more (pre-release channels, build metadata), extend or replace the underlying class rather than fighting the config.