Versioning

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

• Asaba William
• All Contributors

License

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