Composer Distributor Laravel Package

Getting Started

Minimal Setup

1. Install the package via Composer:

   composer require phar-io/composer-distributor
   

2. Locate the core class: The main entry point is PharIo\ComposerDistributor\ComposerDistributor.
3. First use case: Fetch and verify a pinned Composer version in a CI script:

   use PharIo\ComposerDistributor\ComposerDistributor;
   
   $distributor = new ComposerDistributor();
   $composerPhar = $distributor->getComposerPhar('2.5.8');
   echo $composerPhar->getPath(); // Path to the verified PHAR
   

Key Configuration

• Cache directory: Defaults to $HOME/.cache/composer-distributor (override via constructor).
• Verification: Enabled by default (uses Composer’s signature checks).

Implementation Patterns

Workflow: CI/CD Integration

1. Pin Composer versions for reproducibility:

   $distributor = new ComposerDistributor('/path/to/cache');
   $composer = $distributor->getComposerPhar('2.5.8'); // Always uses 2.5.8
   

2. Cache reuse: Subsequent runs reuse cached PHARs (faster, offline-friendly).
3. Post-install hooks: Chain with Composer\Factory for automated dependency resolution:

   $composer = $distributor->getComposerPhar('2.5.8');
   $factory = new Composer\Factory();
   $composer = $factory->create($composer->getPath(), '/path/to/project');
   $composer->run();
   

Advanced Patterns

• Dynamic version selection: Use getLatestStableComposerPhar() for non-pinned setups.
• Custom verification: Extend PharIo\ComposerDistributor\Verifier\ComposerPharVerifier for additional checks.
• Offline mode: Pass false to setVerify() to skip verification (not recommended for security).

Integration Tips

• Laravel Artisan commands: Wrap the distributor in a command for CLI access:

  namespace App\Console\Commands;
  use PharIo\ComposerDistributor\ComposerDistributor;
  
  class UpdateComposer extends Command {
      protected $signature = 'composer:update {version}';
      public function handle(ComposerDistributor $distributor) {
          $phar = $distributor->getComposerPhar($this->argument('version'));
          $this->info("Updated to: {$phar->getVersion()}");
      }
  }
  

• Service Provider binding: Register the distributor as a singleton:

  $this->app->singleton(ComposerDistributor::class, function ($app) {
      return new ComposerDistributor($app['config']['composer.cache']);
  });
  

Gotchas and Tips

Pitfalls

1. Cache collisions: If multiple versions share the same cache dir, ensure unique subdirectories per version.
2. Verification failures: Network issues or corrupted downloads may trigger silent failures. Use try-catch:

   try {
       $phar = $distributor->getComposerPhar('2.5.8');
   } catch (\PharIo\ComposerDistributor\Exception\ComposerPharException $e) {
       $this->error("Composer PHAR verification failed: {$e->getMessage()}");
   }
   

3. PHAR permissions: Ensure the cache directory is writable by the executing user (e.g., chmod -R 755 ~/.cache/composer-distributor).

Debugging

• Verbose output: Enable debug mode via setDebug(true) to log download/verification steps.
• Manual verification: Test PHARs with composer self-update --check after distribution.

Extension Points

1. Custom download sources: Implement PharIo\ComposerDistributor\Downloader\ComposerPharDownloaderInterface for private mirrors.
2. Signature validation: Override PharIo\ComposerDistributor\Verifier\ComposerPharVerifier to use custom keys.
3. Post-download hooks: Extend PharIo\ComposerDistributor\ComposerPhar to add metadata or modify the PHAR.

Configuration Quirks

• Default version: The package defaults to the latest stable version if no argument is provided.
• Offline mode: Disabling verification (setVerify(false)) bypasses all integrity checks—use cautiously in production.

Pro Tips

• Laravel Mix/Valet: Cache PHARs in a shared location (e.g., /opt/composer-cache) for team-wide reuse.
• Docker: Mount the cache directory as a volume to avoid redundant downloads:

  VOLUME ["/path/to/cache"]