README

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 comprehensive framework integration.

Works with ANY PHP framework or vanilla PHP! Laravel, Symfony, CodeIgniter, CakePHP, Slim, and more.

Quick Links:

Which Class to Use? WHICH-CLASS.md - Decision guide

Vanilla PHP: VANILLA-PHP-USAGE.md - Standalone usage

Framework Integration: FRAMEWORK-INTEGRATION.md - 8+ frameworks

Supported: Laravel, Symfony, CodeIgniter, CakePHP, Slim, Yii2, Laminas, Phalcon

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
Universal Integration: Works with Laravel, Symfony, CodeIgniter, CakePHP, Slim, and more
Configurable: Extensive configuration options
Cache Support: PSR-6, PSR-16, and framework-specific caches
Well-tested: Comprehensive test coverage
Zero Dependencies: Works standalone with vanilla PHP or any framework

Requirements

PHP 8.2 or higher
Any PHP framework (Laravel, Symfony, CodeIgniter, etc.) or vanilla PHP
Git installed on your system
Optional: PSR-6 or PSR-16 compatible cache for caching

Installation

Install the package via Composer:

composer require williamug/versioning

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

Vanilla PHP

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)

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();

Option 3: Universal Framework Class (Works with Any Framework)

use Williamug\Versioning\UniversalVersioning;

// Configure with your framework's cache
UniversalVersioning::setRepositoryPath(__DIR__);
UniversalVersioning::setCacheAdapter($yourFrameworkCache); // PSR-6/PSR-16 compatible
UniversalVersioning::setFallbackVersion('1.0.0');

echo UniversalVersioning::tag(); // v1.0.0

Other PHP Frameworks

The package works seamlessly with any PHP framework! See FRAMEWORK-INTEGRATION.md for detailed examples:

Symfony - Full integration with Symfony Cache
CodeIgniter 4 - Library and helper examples
CakePHP 5 - Component and helper integration
Slim 4 - Middleware and DI container setup
Yii2 - Component configuration
Laminas - Service manager integration
Phalcon - DI service registration

Laravel

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

{{-- Simple tag version --}}
<footer>
    Version: @app_version_tag
</footer>

{{-- Full version info --}}
<div>
    Build: @app_version_full
</div>

{{-- Just the commit hash --}}
<div>
    Commit: @app_version_commit
</div>

{{-- Custom format --}}
<div>
    Version: @app_version('tag-commit')
</div>

Using the Helper Function

// In your controllers or views
$version = app_version();
$commit = app_version('commit');

Configuration Options

Repository Path

Specify where your .git directory is located:

'repository_path' => base_path(), // or any absolute path

Caching

Enable caching to improve performance:

'cache' => [
    'enabled' => true,
    'ttl' => 3600, // Cache for 1 hour
    'key' => 'app_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

Choose default format:

'format' => 'tag', // Options: 'tag', 'full', 'commit', 'tag-commit'

Version Prefix

Control whether to include 'v' prefix:

'include_prefix' => false, // Displays: 1.0.0 instead of v1.0.0

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

# Run tests
composer test

# Run tests with coverage
composer test-coverage

# Run static analysis
composer analyse

# Format code
composer format

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

Display Version in Footer

<footer class="text-center py-4">
    <p>MyApp @app_version_tag | Build @app_version_commit</p>
</footer>

API Response

public function version()
{
    return response()->json([
        'version' => Versioning::tag(),
        'commit' => Versioning::commit(),
        'build_date' => now(),
    ]);
}

Admin Dashboard

public function dashboard()
{
    return view('admin.dashboard', [
        'app_version' => Versioning::full(),
        'git_commit' => Versioning::commit(),
    ]);
}

Clear Cache After Deployment

// In your deployment script
Artisan::call('cache:clear');
Versioning::clearCache();

Troubleshooting

"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

git tag v1.0.0
git push origin v1.0.0

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

williamug / versioning

Maintainers

Details