Application Versioning Laravel Package

Getting Started

• Install with composer require the versioning package, then publish its config: php artisan vendor:publish --tag=application-versioning-config (check the package's provider for the exact tag). This creates config/application-versioning.php.
• By default the package reads/writes a local version.yaml at the path in version_file_path. If your app lives on a read-only filesystem (Vapor/Lambda, hardened containers, some Forge/Cloud setups), set the new disk options instead:

  'disk' => env('APP_VERSIONING_DISK'),           // e.g. 's3'
  'disk_path' => env('APP_VERSIONING_DISK_PATH', 'version.yaml'),
  

  When disk is null the local file is used exactly as before, so existing installs need no change.
• First use case: expose the version in a health/status endpoint or a footer. Resolve through the container or facade so you get the singleton:

  use ApplicationVersioning\Facades\ApplicationVersion; // verify exact FQCN in the package
  
  Route::get('/health', fn () => response()->json([
      'version' => ApplicationVersion::getFormatedVersion(),
  ]));
  

• Next, run the package's install/increase commands (php artisan list them under the package namespace) to see how version.yaml is written before wiring it into a pipeline.

Implementation Patterns

• Resolve, don't instantiate. As of 0.2.0 getFormatedVersion(), the install command and the increase command all pull the singleton from the container. Follow suit in your own code — app(ApplicationVersioning::class) or the ApplicationVersion facade — rather than new ApplicationVersioning(...). This keeps a single source of truth for config and any cached read.
• Read once per request, render anywhere. A typical pattern is a view composer or a Blade directive that injects the version into a layout footer, plus a JSON field on a status endpoint. Because the binding is a singleton, repeated calls don't re-read the file/disk.
• Cache-busting assets. Use the same value to suffix asset URLs (?v={{ ApplicationVersion::getFormatedVersion() }}) so a deploy invalidates CDN/browser caches without a separate build number.
• Deploy pipeline bump. In CI, after a successful release, call the increase command against the same disk the runtime reads from. With the new disk support this works from a build container that has no writable checkout — e.g. bump version.yaml on S3, and every app instance picks it up.
• Disk-backed versioning for read-only deployments. This is the headline integration tip: pair APP_VERSIONING_DISK with a disk whose credentials are available at runtime, and keep APP_VERSIONING_DISK_PATH stable across environments. Use distinct paths/buckets per environment (staging vs production) so commands don't bump the wrong version.
• Git hash fallback chain. getFormatedVersion() composes the config version with GitSupport::getCurrentHeadHash(). In 0.2.0 that hash now resolves correctly on a detached HEAD (deployments that check out a commit) and for refs living only in packed-refs (post-git gc, fresh clones). If .git is missing or unreadable at all, the hash defaults to empty rather than throwing — so you can call it unconditionally in health checks without a try/catch.
• Testing. Bind a fake ApplicationVersioning (or point version_file_path/disk at a fixture) in your test case so assertions on version strings don't depend on the repo's .git state.

Gotchas and Tips

• getFormatedVersion() is spelled with one t. It's the public API name; don't "fix" it in your code or you'll get a BadMethodCallException. Consider wrapping it in a small helper of your own (app_version()) to isolate the typo and make it swappable later.
• Singleton + long-running workers. Under Octane or queue workers, the singleton is resolved once per worker lifecycle. If you bump the version mid-process (or change config at runtime), you may serve a stale value — restart workers after a deploy, or resolve per job if you need freshness.
• Publishing the config again. 0.2.0 adds disk and disk_path keys. Existing published configs won't have them; add the two lines manually or re-publish. Note that re-publishing can overwrite local customisations — diff before you confirm.
• config:cache interaction. Env-driven values (APP_VERSIONING_DISK, APP_VERSIONING_DISK_PATH) are baked in at cache time. Changing them requires php artisan config:cache again, which is a common "why is it still writing locally?" cause.
• Two different paths. version_file_path (local) and disk_path (disk) are independent settings. Setting disk silently ignores version_file_path; keep both documented in your .env.example to avoid confusion between environments.
• Write permissions. For the local path, the web user must be able to write version.yaml if you bump from a request; prefer bumping only from CLI/CI so the file isn't a writable web target. For disks, verify the disk's throw behaviour — a failed write from the increase command is easier to catch than an empty read at runtime.
• Debugging version mismatches. Check in this order: cached config, APP_VERSIONING_DISK actually set in the running process, disk_path contents, then the local file. When the git hash is empty in the output, confirm .git is present and readable in the deployed artifact — many build images strip it, and 0.2.0's new default-on-error means you'll get a version without a hash rather than an exception, which can mask the real cause.
• Version constraints. symfony/yaml is now ^7.1|^8.0 for Laravel 13 compatibility, and tests cover Laravel 11/12/13. Laravel 10 (Symfony 6) is effectively out of range, so pin accordingly if you're still on it. No breaking changes in this release, so the upgrade is a composer update plus the optional config keys.