Versioning Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Semantic Versioning Alignment: The package aligns well with modern PHP/Symfony applications requiring SemVer 2.0.0 compliance, particularly for CI/CD pipelines, changelog generation, and API versioning.
• Symfony-Centric: Designed for Symfony Flex (2/3/4/5), but can be adapted for Laravel via Symfony Bridge or standalone PHP integration (e.g., via Composer autoloading).
• Extensibility: Supports custom version providers (e.g., GitLab CI variables, custom files), making it adaptable to non-Git workflows (e.g., Docker tags, Capistrano).
• Lightweight: Minimal overhead; version resolution happens at runtime (not compile-time), avoiding build complexity.

Integration Feasibility

• Laravel Compatibility:
  • Symfony Components: Laravel can leverage Symfony’s nikolaposa/version library directly (via composer require nikolaposa/version).
  • Service Container: The bundle’s VersionProvider pattern can be replicated in Laravel’s Service Provider or Facade (e.g., VersionService).
  • Twig Alternative: Replace Twig globals with Laravel’s Blade directives or View Composers.
• Git Integration: Works seamlessly with Laravel’s Git hooks or CI (e.g., GitHub Actions) to auto-tag releases.
• Manual Override: Supports fallback to VERSION files or environment variables (e.g., APP_VERSION in .env).

Technical Risk

• Symfony Dependency: Direct use requires Symfony components, adding ~10MB to vendor size. Mitigate by extracting only the nikolaposa/version library.
• Version Provider Gaps: Laravel’s deployment workflows (e.g., Forge, Envoyer) may not align with Capistrano’s REVISION file. Requires custom provider.
• Testing Overhead: No Laravel-specific tests; validation needed for edge cases (e.g., detached Git HEAD, missing tags).
• Caching: Runtime version resolution could impact cold starts. Cache the version in Laravel’s config cache or Redis.

Key Questions

1. Deployment Workflow:
   • How are releases tagged in Git? (Manual? CI-triggered?)
   • Are non-Git version sources (e.g., Docker images, CI build IDs) needed?
2. Performance:
   • Is version resolution a bottleneck? (E.g., in high-traffic APIs.)
3. Display Requirements:
   • Where is the version exposed? (UI, API headers, logs?)
   • Need for human-readable (e.g., "v1.2.3") vs. machine-readable (e.g., 1.2.3) formats?
4. Fallback Strategy:
   • What’s the default version if Git tags are missing? (e.g., 0.0.0-dev.)
5. Security:
   • Should version exposure be restricted in production? (E.g., hide from public APIs.)

Integration Approach

Stack Fit

• Core Components:
  • Version Resolution: Use nikolaposa/version library directly (no full bundle).
  • Service Layer: Create a Laravel VersionService to aggregate providers (Git, file, env vars).
  • Facade: Expose version() helper (e.g., app()->version()).
  • Blade/Twig: Use a View Composer to inject version into layouts.
• Alternatives:
  • APIs: Add version to HTTP headers via Middleware.
  • CLI: Expose via php artisan version command.

Migration Path

1. Phase 1: Core Integration

   • Install nikolaposa/version and create a VersionService:

     // app/Services/VersionService.php
     use Nikolaposa\Version\Version;
     use Nikolaposa\Version\Provider\GitRepositoryProvider;
     
     class VersionService {
         public function get(): string {
             $provider = new GitRepositoryProvider(__DIR__.'/../../');
             return (new Version())->setProvider($provider)->get();
         }
     }
     

   • Register in AppServiceProvider:

     $this->app->singleton(VersionService::class, fn() => new VersionService());
     

2. Phase 2: Extensibility

   • Add custom providers (e.g., EnvProvider for .env):

     class EnvProvider implements ProviderInterface {
         public function getVersion(): string {
             return env('APP_VERSION', '0.0.0-dev');
         }
     }
     

   • Chain providers (fallback logic):

     $version = (new Version())
         ->setProvider(new GitRepositoryProvider())
         ->setProvider(new EnvProvider())
         ->get();
     

3. Phase 3: UI/API Exposure

   • Blade: @inject('version', 'App\Services\VersionService') in layouts.
   • API: Middleware to set X-Api-Version header.
   • CLI: Artisan command:

     Artisan::command('version', fn() => echo app(VersionService::class)->get());
     

Compatibility

• Laravel Versions: Tested on Laravel 8+ (Symfony 5+ components).
• Git Requirements: Assumes standard Git workflow. For bare repos, use GitRepositoryProvider with --git-dir.
• Non-Git Environments: Fallback to VERSION file or APP_VERSION env var.

Sequencing

1. Pre-Release:
   • Tag commits with git tag -a v1.2.3 -m "Release".
   • Push tags: git push --tags.
2. CI/CD:
   • Use Git tags to trigger releases (e.g., GitHub Actions).
   • Inject version into APP_VERSION env var for fallback.
3. Runtime:
   • Version resolved on first request (cache in config('version') after first call).

Operational Impact

Maintenance

• Provider Updates: Monitor nikolaposa/version for SemVer changes.
• Custom Providers: Maintain custom logic (e.g., Docker tag parsing) separately.
• Deprecation: Symfony 6+ may require adapter updates.

Support

• Debugging:
  • Log provider failures (e.g., missing Git tags).
  • Expose php artisan version:debug to inspect providers.
• Documentation:
  • Add README section for Laravel setup.
  • Note fallback behavior for non-Git environments.

Scaling

• Performance:
  • Cache resolved version in config('version') or Redis (TTL: 1 hour).
  • Avoid Git calls in high-frequency contexts (e.g., API requests).
• Distributed Systems:
  • Sync version across microservices via config management (e.g., Consul).

Failure Modes

Ramp-Up

• Developer Onboarding:
  • Document APP_VERSION override for local dev.
  • Example: APP_VERSION=1.2.3-dev in .env.
• CI/CD Training:
  • Add step to tag releases (e.g., git tag -f v${{ github.ref_name }}).
• Testing:
  • Unit test VersionService with mocked providers.
  • Integration test Blade/API version exposure.