PHPackages williamug/versioning - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. williamug/versioning ActiveLibrary[Utility & Helpers](/categories/utility) williamug/versioning ==================== A PHP package that helps you display the version of your Laravel or vanilla PHP application by leveraging git version tags v3.1.0(4mo ago)12.6k1MITPHPPHP ^8.2CI passing Since Apr 10Pushed 4mo ago1 watchersCompare [ Source](https://github.com/Williamug/versioning)[ Packagist](https://packagist.org/packages/williamug/versioning)[ Docs](https://github.com/williamug/versioning)[ GitHub Sponsors](https://github.com/Williamug)[ RSS](/packages/williamug-versioning/feed)WikiDiscussions main Synced 3w ago READMEChangelog (10)Dependencies (12)Versions (18)Used By (1) Versioning ========== [](#versioning) [![Latest Version on Packagist](https://camo.githubusercontent.com/37508dc848c2c58a138199f48b9fd1d208b55970b0658f1b5ab2f6f2fdce07e2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f77696c6c69616d75672f76657273696f6e696e672e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/williamug/versioning)[![GitHub Tests Action Status](https://camo.githubusercontent.com/a1906a6cfde028b94d97f359918ed3ec4e7520d73da21196bcbb50d1fa9bff02/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f77696c6c69616d75672f76657273696f6e696e672f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/williamug/versioning/actions?query=workflow%3Arun-tests+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/e7bc333da0bfd7fded495df756d52a3761c95e2c59bfce56578f55a52a9e1a4b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f77696c6c69616d75672f76657273696f6e696e672e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/williamug/versioning)[![License](https://camo.githubusercontent.com/71c6c1ede1d9b13acf321e179ab4d50b0b45c5b849066f57bafbe6a8b698254e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f77696c6c69616d75672f76657273696f6e696e672e7376673f7374796c653d666c61742d737175617265)](https://github.com/williamug/versioning/blob/master/LICENSE.md) A robust PHP package that helps you display your application's version by leveraging Git tags. Features include caching, multiple format options, error handling, and support for both Laravel and vanilla PHP applications. **Works with Laravel and vanilla PHP!** > **Quick Links:** > > - **Vanilla PHP**: [VANILLA-PHP-USAGE.md](VANILLA-PHP-USAGE.md) - Standalone usage without Laravel > - **FTP Deployment**: [FTP-DEPLOYMENT.md](FTP-DEPLOYMENT.md) - Deploy via FTP without git Features -------- [](#features) - **Multiple Version Formats**: Tag, full, commit hash, or tag with commit - **Performance**: Built-in caching support to minimize Git command executions - **Secure**: Proper input sanitization and error handling - **Laravel Integration**: Seamless integration with Laravel's facade and Blade directives - **Vanilla PHP Support**: Works standalone without any framework - **Configurable**: Extensive configuration options - **FTP Deployment Support**: Works with deployments that don't include git history - **Well-tested**: Comprehensive test coverage Requirements ------------ [](#requirements) - PHP 8.2 or higher - Laravel 10.x, 11.x, or 12.x (for Laravel integration) or vanilla PHP - Git installed on your system - Optional: Laravel Cache for caching (automatically available in Laravel) Installation ------------ [](#installation) Install the package via Composer: ``` composer require williamug/versioning ``` ### Laravel Configuration (Optional) [](#laravel-configuration-optional) Publish the configuration file: ``` php artisan vendor:publish --tag="versioning-config" ``` This creates `config/versioning.php` where you can customize: ``` return [ 'repository_path' => base_path(), 'cache' => [ 'enabled' => true, 'ttl' => 3600, // 1 hour 'key' => 'app_version', ], 'fallback_version' => env('APP_VERSION', 'dev'), 'format' => 'tag', 'include_prefix' => true, ]; ``` Usage ----- [](#usage) ### Vanilla PHP [](#vanilla-php) #### Option 1: Using the Helper Function (Simplest) [](#option-1-using-the-helper-function-simplest) ``` require __DIR__ . '/vendor/autoload.php'; // Simple usage echo app_version(); // v1.0.0 // Different formats echo app_version('tag'); // v1.0.0 echo app_version('full'); // v1.0.0-5-g123abc echo app_version('commit'); // 123abc echo app_version('tag-commit'); // v1.0.0-123abc ``` #### Option 2: Using the Standalone Class (More Features) [](#option-2-using-the-standalone-class-more-features) ``` require __DIR__ . '/vendor/autoload.php'; use Williamug\Versioning\StandaloneVersioning; // Configure (optional) StandaloneVersioning::setRepositoryPath(__DIR__); StandaloneVersioning::setFallbackVersion('1.0.0'); StandaloneVersioning::setCaching(true, 3600); StandaloneVersioning::setIncludePrefix(true); // Get version echo StandaloneVersioning::tag(); // v1.0.0 echo StandaloneVersioning::full(); // v1.0.0-5-g123abc echo StandaloneVersioning::commit(); // 123abc echo StandaloneVersioning::tagWithCommit(); // v1.0.0-123abc // Clear cache when needed StandaloneVersioning::clearCache(); ``` See [VANILLA-PHP-USAGE.md](VANILLA-PHP-USAGE.md) for complete standalone usage guide. ### Laravel [](#laravel) #### Using the Facade [](#using-the-facade) ``` use Williamug\Versioning\Versioning; // Get version tag Versioning::tag(); // v1.0.0 // Get full version info Versioning::full(); // v1.0.0-5-g123abc // Get commit hash Versioning::commit(); // 123abc // Get tag with commit Versioning::tagWithCommit(); // v1.0.0-123abc // Clear version cache Versioning::clearCache(); ``` #### Using Blade Directives [](#using-blade-directives) ``` {{-- Simple tag version --}} Version: @app_version_tag {{-- Full version info --}} Build: @app_version_full {{-- Just the commit hash --}} Commit: @app_version_commit {{-- Custom format --}} Version: @app_version('tag-commit') ``` #### Using the Helper Function [](#using-the-helper-function) ``` // In your controllers or views $version = app_version(); $commit = app_version('commit'); ``` Configuration Options --------------------- [](#configuration-options) ### Repository Path [](#repository-path) Specify where your `.git` directory is located: ``` 'repository_path' => base_path(), // or any absolute path ``` ### Caching [](#caching) Enable caching to improve performance: ``` 'cache' => [ 'enabled' => true, 'ttl' => 3600, // Cache for 1 hour 'key' => 'app_version', ], ``` ### Fallback Version [](#fallback-version) Set a default version when Git is unavailable: ``` 'fallback_version' => env('APP_VERSION', 'dev'), ``` You can set this in your `.env`: ``` APP_VERSION=v1.0.0 ``` ### Version Format [](#version-format) Choose default format: ``` 'format' => 'tag', // Options: 'tag', 'full', 'commit', 'tag-commit' ``` ### Version Prefix [](#version-prefix) Control whether to include 'v' prefix: ``` 'include_prefix' => false, // Displays: 1.0.0 instead of v1.0.0 ``` Error Handling -------------- [](#error-handling) The package gracefully handles errors: - Returns fallback version if Git is not installed - Returns fallback version if not in a Git repository - Returns fallback version if no tags exist - Catches and handles all exceptions Testing ------- [](#testing) ``` # Run tests composer test # Run tests with coverage composer test-coverage # Run static analysis composer analyse # Format code composer format ``` Development ----------- [](#development) ``` # Install dependencies composer install # Run Pint (code formatting) vendor/bin/pint # Run PHPStan (static analysis) vendor/bin/phpstan analyse # Run Pest (tests) vendor/bin/pest ``` Common Use Cases ---------------- [](#common-use-cases) ### Display Version in Footer [](#display-version-in-footer) ``` MyApp @app_version_tag | Build @app_version_commit ``` ### API Response [](#api-response) ``` public function version() { return response()->json([ 'version' => Versioning::tag(), 'commit' => Versioning::commit(), 'build_date' => now(), ]); } ``` ### Admin Dashboard [](#admin-dashboard) ``` public function dashboard() { return view('admin.dashboard', [ 'app_version' => Versioning::full(), 'git_commit' => Versioning::commit(), ]); } ``` ### Clear Cache After Deployment [](#clear-cache-after-deployment) ``` // In your deployment script Artisan::call('cache:clear'); Versioning::clearCache(); ``` Troubleshooting --------------- [](#troubleshooting) ### "dev" is always displayed [](#dev-is-always-displayed) - Ensure you're in a Git repository - Ensure Git is installed: `git --version` - Ensure you have tags: `git tag` - Check your repository path in config ### Create a tag if none exist [](#create-a-tag-if-none-exist) ``` git tag v1.0.0 git push origin v1.0.0 ``` Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Contributing ------------ [](#contributing) Please see [CONTRIBUTING](CONTRIBUTING.md) for details. Security Vulnerabilities ------------------------ [](#security-vulnerabilities) Please review [our security policy](../../security/policy) on how to report security vulnerabilities. Credits ------- [](#credits) - [Asaba William](https://github.com/williamug) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 46 — FairBetter than 92% of packages Maintenance77 Regular maintenance activity Popularity22 Limited adoption so far Community9 Small or concentrated contributor base Maturity62 Established project with proven stability Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~48 days Recently: every ~168 days Total 15 Last Release 125d ago Major Versions v1.0.4 → v2.0.02024-04-16 v2.0.3 → v3.0.02025-12-01 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/15543507?v=4)[williamDk](/maintainers/williamug)[@Williamug](https://github.com/Williamug) --- Top Contributors [![Williamug](https://avatars.githubusercontent.com/u/15543507?v=4)](https://github.com/Williamug "Williamug (135 commits)") --- Tags application-versionlaravelversioningphplaravelversioningversion controlWilliamuggit tags ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/williamug-versioning/health.svg) ``` [![Health](https://phpackages.com/badges/williamug-versioning/health.svg)](https://phpackages.com/packages/williamug-versioning) ``` ### Alternatives [spatie/laravel-pdf Create PDFs in Laravel apps 1.0k4.3M42](/packages/spatie-laravel-pdf)[codewithdennis/filament-select-tree The multi-level select field enables you to make single selections from a predefined list of options that are organized into multiple levels or depths. 328482.0k25](/packages/codewithdennis-filament-select-tree)[nativephp/desktop NativePHP for Desktop 38133.6k8](/packages/nativephp-desktop)[rawilk/profile-filament-plugin Profile & MFA starter kit for filament. 3913.7k](/packages/rawilk-profile-filament-plugin)[tapp/filament-google-autocomplete-field Filament plugin that provides a Google Autocomplete field 30122.2k](/packages/tapp-filament-google-autocomplete-field)[tapp/filament-form-builder User facing form builder using Filament components 141.9k2](/packages/tapp-filament-form-builder) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)