Hook Installer Laravel Package

Getting Started

Minimal Setup

1. Prerequisites:

   • Install captainhook/captainhook or captainhook/captainhook-phar in your project.
   • Ensure PHP ≥8.0 is installed.

2. Install the Plugin:

   composer require --dev captainhook/hook-installer
   

   This registers the Composer plugin automatically.

3. First Use Case: After running composer install or composer update, CaptainHook hooks will be automatically activated in your .git/hooks directory. No manual captainhook install command is needed.

Implementation Patterns

Workflow Integration

1. Standard Laravel Workflow:

   • Add to composer.json under require-dev:

     "captainhook/hook-installer": "^1.0"
     

   • Commit this change. On the next composer install, hooks are installed without manual intervention.

2. Custom Hook Configuration:

   • Place your captainhook.json in a non-default location (e.g., config/captainhook.json).
   • Configure the installer in composer.json:

     "extra": {
       "captainhook": {
         "config": "config/captainhook.json"
       }
     }
     

3. CI/CD Pipelines:

   • Use composer install --no-dev in CI, then explicitly run:

     composer hook-install  # If needed for testing hooks
     

   • For Laravel Forge/Laravel Vapor, ensure hooks are installed post-deploy via a script:

     composer install --prefer-dist --no-interaction --optimize-autoloader
     composer hook-install
     

4. Team Onboarding:

   • Document the composer.json changes in your CONTRIBUTING.md.
   • Example snippet:

     ## Git Hooks
     Run `composer install` to automatically set up CaptainHook. No additional steps required.
     

Gotchas and Tips

Pitfalls

1. PHP Binary Path:

   • If php is not in $PATH, the installer may fail. Fix by:
     • Explicitly setting the PHP path in composer.json:

       "extra": {
         "captainhook": {
           "exec": "/path/to/php tools/captainhook.phar"
         }
       }
       

     • Or ensure php is in your system PATH.

2. Disabled Plugin:

   • If disable-plugin is set to true in composer.json, the installer silently skips hook installation.
   • Debug by checking:

     composer config extra.captainhook.disable-plugin
     

3. Hook Overwrites:

   • The installer replaces existing .git/hooks if they conflict. Backup hooks manually if needed:

     mv .git/hooks .git/hooks.bak
     

4. Composer Version Conflicts:

   • Requires Composer ≥2.0. If using an older version, pin the plugin:

     "require": {
       "composer-plugin-api": "~1.0"
     }
     

Debugging

• Verbose Output: Run with -v to see installation steps:

  composer install -v
  

• Dry Run: Test configuration without installing:

  composer hook-install --dry-run
  

Extension Points

1. Conditional Installation: Use only-enabled: true to skip disabled hooks (e.g., for optional pre-commit checks):

   "extra": {
     "captainhook": {
       "only-enabled": true
     }
   }
   

2. Force Install: Override user preferences with force-install: true (useful for shared environments):

   "extra": {
     "captainhook": {
       "force-install": true
     }
   }
   

3. Custom Scripts: Extend the plugin by creating a post-install script in composer.json:

   "scripts": {
     "post-install-cmd": [
       "@hook-installer",
       "php artisan hook:verify"  # Custom Laravel command
     ]
   }
   

Laravel-Specific Tips

• Artisan Integration: Create a custom Artisan command to verify hooks:

  // app/Console/Commands/VerifyHooks.php
  public function handle() {
      $this->info('Checking CaptainHook status...');
      $output = shell_exec('captainhook status');
      $this->line($output);
  }
  

  Register it in app/Console/Kernel.php:

  protected $commands = [
      Commands\VerifyHooks::class,
  ];
  

• Environment-Specific Hooks: Use Laravel’s environment files to toggle hooks:

  // composer.json
  "extra": {
    "captainhook": {
      "config": "config/captainhook.{{ env('APP_ENV') }}.json"
    }
  }