Zend Version Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require zendframework/zend-version
   

   Add to composer.json under require (if not auto-installed).

2. Basic Usage

   use Zend\Version\Version;
   
   $version = new Version('1.2.3');
   echo $version->getVersion(); // Outputs: "1.2.3"
   

3. First Use Case Validate and compare software versions in a Laravel app (e.g., API versioning, dependency checks, or user-agent parsing):

   $requestVersion = new Version(request('version'));
   $supportedVersion = new Version('2.0.0');
   
   if ($requestVersion->compare($supportedVersion) >= 0) {
       // Proceed with API logic
   }
   

4. Where to Look First

   • Zend\Version\Version (core class).
   • Tests for edge cases (e.g., 1.2.3-beta, v2.0.0).

Implementation Patterns

Core Workflows

1. Version Parsing and Validation

   $version = new Version('1.2.3-alpha');
   if ($version->isValid()) {
       // Handle valid version (e.g., store in DB or log)
   }
   

2. Comparison Logic

   • API Versioning:

     $clientVersion = new Version(request()->header('X-API-Version'));
     $currentVersion = new Version(config('api.version'));
     
     if ($clientVersion->compare($currentVersion) < 0) {
         abort(406, 'Unsupported API version');
     }
     

   • Dependency Checks:

     $requiredVersion = new Version('3.1.0');
     $installedVersion = new Version(app()->version()); // Hypothetical Laravel version getter
     
     if ($requiredVersion->compare($installedVersion) > 0) {
         throw new \RuntimeException('Laravel version too old');
     }
     

3. User-Agent Parsing

   $userAgent = request()->userAgent();
   $version = new Version($userAgent); // May throw on invalid formats
   $minSupported = new Version('1.0.0');
   
   if ($version->compare($minSupported) >= 0) {
       // Allow access
   }
   

4. Semantic Versioning Utilities

   $version = new Version('2.0.0');
   echo $version->getMajor(); // 2
   echo $version->getMinor(); // 0
   echo $version->getPatch(); // 0
   echo $version->getPrerelease(); // "" (empty for stable)
   

Integration Tips

• Laravel Service Provider: Bind the Version class for dependency injection:

  $this->app->bind('version', function () {
      return new \Zend\Version\Version(config('app.version'));
  });
  

  Use in controllers:

  public function __construct(private Version $appVersion) {}
  

• Middleware for Version Checks:

  public function handle($request, Closure $next) {
      $requestVersion = new Version($request->header('X-Version'));
      if ($requestVersion->compare(new Version('1.0.0')) < 0) {
          return response()->json(['error' => 'Unsupported'], 400);
      }
      return $next($request);
  }
  

• Artisan Commands: Validate package versions during deployment:

  public function handle() {
      $required = new Version('1.2.0');
      $installed = new Version($this->getComposerVersion('vendor/package'));
  
      if ($required->compare($installed) > 0) {
          $this->error("Package version too old: {$installed->getVersion()}");
      }
  }
  

Gotchas and Tips

Pitfalls

1. Strict Validation

   • Zend\Version\Version throws \InvalidArgumentException for malformed versions (e.g., '1.2', 'v1.2.3').
   • Fix: Use Version::isValid($string) to check first or wrap in a try-catch.

2. Prerelease Handling

   • Prereleases (e.g., 1.0.0-alpha) are not considered greater than stable versions (e.g., 1.0.0).
   • Tip: Use Version::compare() carefully in production if prereleases are part of your workflow.

3. No Laravel-Specific Features

   • The package is framework-agnostic. You’ll need to manually integrate with Laravel’s config, requests, or services.

4. Archived Status

   • The package is no longer maintained. Use at your own risk or fork it for critical projects.
   • Alternative: Consider composer-semver or Laravel’s built-in illuminate/support version helpers (if available).

Debugging

• Invalid Version Strings:

  try {
      $version = new Version('invalid-version');
  } catch (\InvalidArgumentException $e) {
      Log::error("Version parsing failed: {$e->getMessage()}");
  }
  

• Unexpected Comparisons:

  • Prereleases are always less than stable versions. If this breaks your logic:

    $a = new Version('1.0.0-alpha');
    $b = new Version('1.0.0');
    var_dump($a->compare($b)); // int(-1) (prerelease < stable)
    

Extension Points

1. Custom Version Formats Extend the Version class to support non-semver formats (e.g., YYYYMMDD):

   class CustomVersion extends \Zend\Version\Version {
       public static function fromDateString(string $date): self {
           $version = new self(str_replace(['-', '.'], '', $date));
           return $version;
       }
   }
   

2. Laravel Facade Create a facade for convenience:

   // app/Facades/Version.php
   namespace App\Facades;
   use Illuminate\Support\Facades\Facade;
   class Version extends Facade {
       protected static function getFacadeAccessor() {
           return 'version';
       }
   }
   

   Usage:

   \App\Facades\Version::compare(new \Zend\Version\Version('1.0.0'));
   

3. Database Versioning Store versions as strings in Laravel migrations and validate on retrieval:

   $storedVersion = new Version(Software::find(1)->version);
   if (!$storedVersion->isValid()) {
       // Handle invalid data
   }
   

Configuration Quirks

• No Built-in Config: The package has no Laravel-specific config file. Store version strings in config/app.php or environment variables:

  APP_VERSION=1.2.3
  

  Retrieve via:

  $version = new Version(config('app.version'));
  

• Case Sensitivity: Version strings are case-sensitive (e.g., '1.2.3' ≠ '1.2.3-BETA'). Normalize case if needed:

  $version = new Version(strtolower($input));