Package Actions Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dreimus/package-actions --dev
   

   Add to composer.json under extra:

   "package-actions": {
     "post-install": ["vendor/bin/your-script.sh"],
     "post-update": ["app/Console/Commands/YourCommand.php"]
   }
   

2. First Use Case:

   • Define a script or command in post-install or post-update to run after package installation/updates.
   • Example: Auto-generate config files or run migrations tied to a specific package.

Implementation Patterns

Workflow Integration

• Post-Install Actions: Use for one-time setup tasks (e.g., copying .env files, running php artisan commands).

  "package-actions": {
    "post-install": ["vendor/bin/generate-config", "php artisan migrate"]
  }
  

• Post-Update Actions: Ideal for version-specific tasks (e.g., schema updates, cache clearing).

  "package-actions": {
    "post-update": ["php artisan vendor:publish --provider=YourPackage\\ServiceProvider"]
  }
  

• Conditional Execution: Combine with composer.json scripts or Laravel’s Artisan::call() for dynamic logic.

  // In a custom command
  if (app()->environment('local')) {
      Artisan::call('your:local-post-install');
  }
  

Laravel-Specific Tips

• Service Provider Hooks: Register actions in register() or boot() for tighter integration.

  public function boot()
  {
      if ($this->app->runningInConsole()) {
          $this->commands([
              \YourPackage\Console\PostInstallCommand::class,
          ]);
      }
  }
  

• Event Listeners: Trigger custom events post-install/update to decouple logic.

  event(new \YourPackage\Events\PackageInstalled($packageName));
  

Gotchas and Tips

Pitfalls

• Order of Execution: Actions run after composer install/update completes. Avoid assuming dependencies are loaded prematurely.

  • Fix: Use composer post-autoload-dump if actions require autoloaded classes.

• Environment Awareness: Scripts/commands may run in non-web contexts (e.g., CLI). Test with:

  COMPOSER=1 php artisan your:command
  

• Debugging: Redirect output to a log file for troubleshooting:

  "post-install": ["your-script.sh >> /tmp/package-actions.log 2>&1"]
  

Extension Points

• Custom Commands: Extend Illuminate\Console\Command for reusable actions.

  // app/Console/Commands/GenerateConfig.php
  class GenerateConfig extends Command {
      protected $signature = 'your:generate-config';
      public function handle() { ... }
  }
  

• Configuration Validation: Validate package-actions entries in a composer.json schema or CI pipeline.

  # Example: Fail if post-install is missing
  if ! grep -q '"post-install"' composer.json; then
      echo "Error: Missing post-install actions." >&2
      exit 1
  fi
  

• Cross-Platform Paths: Use realpath() or Laravel’s storage_path() for filesystem operations to avoid path issues.

  $path = storage_path('app/package-config');