Composer Downloads Plugin Laravel Package

Getting Started

This package, composer-downloads-plugin, is a lightweight Composer plugin designed to simplify tracking and managing package download statistics for PHP projects. It integrates seamlessly with Laravel projects to provide insights into package adoption without requiring manual instrumentation.

Minimal Steps

1. Installation: Add the plugin to your project's composer.json under "extra":

   {
       "extra": {
           "composer-downloads-plugin": {
               "apiKey": "your_api_key_here", // Optional, if using a hosted service
               "command-class": "App\\Composer\\CustomTrackCommand" // Optional override
           }
       }
   }
   

   Run composer require pact-foundation/composer-downloads-plugin.

2. First Use Case: After installation, the plugin automatically tracks package downloads via Composer's post-update-cmd and post-install-cmd hooks. For Laravel projects, leverage this to:

   • Monitor dependency adoption in CI/CD pipelines (now with explicit PHP 8.4/8.5 and Symfony 8 support).
   • Trigger custom Laravel events (e.g., PackageDownloaded) via Composer scripts:

     {
         "scripts": {
             "post-update-cmd": [
                 "@composer-downloads-plugin track",
                 "php artisan event:dispatch PackageDownloaded"
             ]
         }
     }
     

Implementation Patterns

Usage Patterns

1. Automatic Tracking with Symfony 8/Laravel: The plugin now officially supports Symfony 8. Ensure your composer.json includes the plugin under "extra" (no conflicts with Symfony's built-in plugins). Example for Laravel:

   # .github/workflows/ci.yml
   jobs:
     test:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: composer install --no-interaction
         - run: composer downloads:track  # Explicitly trigger tracking
   

2. PHP 8.4/8.5 Integration:

   • Tested compatibility with PHP 8.4/8.5. Use composer why-not pact-foundation/composer-downloads-plugin to verify constraints.
   • For legacy stacks (<8.1), manually override the command class or fork the package.

3. Custom API Endpoints: Extend the plugin to use self-hosted APIs by configuring endpoint and apiKey in composer.json:

   {
       "extra": {
           "composer-downloads-plugin": {
               "endpoint": "https://your-service.com/api/downloads",
               "apiKey": "your_key"
           }
       }
   }
   

Workflows

• CI/CD Pipelines: Integrate the plugin into GitHub Actions, GitLab CI, or Laravel Forge to log downloads per deployment.
• Dependency Audits: Cross-reference download stats with Laravel's composer.json to identify unused packages (now with Symfony 8 compatibility).

Gotchas and Tips

Pitfalls

1. macOS Command Resolution:

   • Issue: Latest macOS versions may fail with "command not found" due to path resolution.
   • Fix: Use the fully qualified path:

     $(composer show -s pact-foundation/composer-downloads-plugin)/vendor/bin/composer downloads:track
     

   • Workaround: Add Composer's bin directory to PATH:

     export PATH="$PATH:$HOME/.composer/vendor/bin"
     

   • Note: The plugin now correctly handles exit codes for these scenarios (verified in v2.2.0).

2. Symfony 8 Plugin Conflicts:

   • Ensure no conflicts with Symfony's built-in Composer plugins. Explicitly order plugins in composer.json:

     {
         "config": {
             "platform-check": false,
             "sort-packages": true
         }
     }
     

3. PHP Version Quirks:

   • PHP 8.4/8.5: Fully supported. Test thoroughly if using legacy stacks (<8.1).
   • Tip: Use composer validate to check for version conflicts.

Debugging

• Verbose Mode: Run Composer with -vvv to debug plugin execution:

  composer install -vvv
  

  Look for logs like [ComposerDownloadsPlugin] Tracking package: vendor/package.

• Exit Code Handling: The plugin now correctly returns exit codes (e.g., 1 for "command not found"). Use echo $? to verify.

Extension Points

1. Custom Events in Laravel: Listen to the DownloadTracked event to extend functionality:

   // app/Providers/ComposerDownloadsServiceProvider.php
   namespace App\Providers;
   use PactFoundation\ComposerDownloadsPlugin\Events\DownloadTracked;
   use Illuminate\Support\ServiceProvider;
   
   class ComposerDownloadsServiceProvider extends ServiceProvider
   {
       public function boot()
       {
           DownloadTracked::listen(function ($event) {
               \Log::info('Package downloaded', ['package' => $event->package]);
           });
       }
   }
   

2. Override Command Logic: Extend the plugin by overriding the TrackCommand class:

   {
       "extra": {
           "composer-downloads-plugin": {
               "command-class": "App\\Composer\\CustomTrackCommand"
           }
       }
   }
   

3. Self-Hosted API Extensions: Fork the package and extend PactFoundation\ComposerDownloadsPlugin\Client\ApiClient for custom authentication or rate limiting.