Captainhook Phar Laravel Package

Getting Started

Minimal Steps

1. Install the PHAR:

   composer require --dev captainhook/captainhook-phar
   

   This places the executable at vendor/bin/hook and updates it on composer update.

2. Initialize Hooks:

   vendor/bin/hook init
   

   This generates a default hooks/ directory in your project root (or .git/hooks/ if configured).

3. Define a Hook: Create a hooks.yml (or hook.php) in your project root with a basic pre-commit hook:

   hooks:
     pre-commit:
       - "php artisan test --env=testing"
       - "php vendor/bin/pint"
   

4. Test Locally:

   git commit -m "test hook"
   

   Verify the commands run before the commit succeeds.

Where to Look First

• CaptainHook Documentation for hook syntax, YAML/JSON config, and advanced use cases.
• GitHub Releases to check for critical updates (last release: 5.6.0).
• vendor/bin/hook --help for CLI options (e.g., hook list, hook run).

First Use Case: Enforcing Pre-Commit Tests

# hooks.yml
hooks:
  pre-commit:
    - "php artisan test --env=testing --parallel"
    - "php vendor/bin/psalm --no-cache"

Why?

• Blocks bad commits early (e.g., failing tests or static analysis).
• Reduces CI flakiness by catching issues locally.
• Works seamlessly with Laravel’s Artisan commands.

Implementation Patterns

Usage Patterns

1. Laravel-Specific Hooks

Leverage Artisan commands in hooks for Laravel-centric workflows:

hooks:
  pre-push:
    - "php artisan migrate:status --env=production"
    - "php artisan queue:work --once --env=testing"

Pattern: Use --env flags to target specific environments.

2. Conditional Hooks

Skip hooks based on file changes or environment:

hooks:
  pre-commit:
    - "php artisan test --env=testing --filter=Unit"
    - "php vendor/bin/pint --test"  # Only lint changed files

Tool: Use git diff --name-only in a shell script wrapper if needed.

3. CI/CD Integration

Trigger hooks in GitHub Actions or GitLab CI:

# .github/workflows/ci.yml
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: composer install
      - run: vendor/bin/hook run pre-commit  # Run hooks in CI
      - run: php artisan test

4. Shared Hooks Across Repos

Use a template repo or Git submodule to share hooks.yml:

git submodule add https://github.com/org/shared-hooks.git vendor/shared-hooks

Then symlink or merge the config into your project.

Workflows

Developer Workflow

1. Setup:

   composer require --dev captainhook/captainhook-phar
   vendor/bin/hook init
   

2. Daily Use:

   git commit -m "feat: add user auth"  # Triggers pre-commit hooks
   

3. Debugging:

   vendor/bin/hook run pre-commit --verbose
   

CI Workflow

1. Install and Run Hooks:

   composer install --no-dev
   composer require --dev captainhook/captainhook-phar
   vendor/bin/hook run pre-commit
   

2. Fail Fast: Add a step to exit CI if hooks fail:

   - name: Run Hooks
     run: vendor/bin/hook run pre-commit || exit 1
   

Integration Tips

Laravel Artisan Integration

Create a custom Artisan command to manage hooks:

php artisan make:command HookManager

// app/Console/Commands/HookManager.php
public function handle()
{
    $this->call('hook:init');
    $this->info('Hooks initialized!');
}

Register it in app/Console/Kernel.php:

protected $commands = [
    \App\Console\Commands\HookManager::class,
];

Now run hooks via:

php artisan hook:init

Environment-Specific Hooks

Use Laravel’s config system to load hooks dynamically:

// config/hook.php
return [
    'hooks' => [
        'pre-commit' => [
            env('APP_ENV') === 'local'
                ? ['php artisan test']
                : ['php artisan test --env=staging'],
        ],
    ],
];

Logging Hook Output

Redirect hook output to Laravel’s log:

hooks:
  pre-commit:
    - "php artisan test --env=testing | tee -a storage/logs/hook.log"

Or use a shell wrapper:

#!/bin/sh
php artisan test --env=testing >> storage/logs/hook.log 2>&1

Gotchas and Tips

Pitfalls

1. Permission Issues:

   • Problem: Hooks fail with "Permission denied" in .git/hooks/.
   • Fix: Ensure hooks are executable:

     chmod +x .git/hooks/*
     

   • Prevention: Use a dedicated hooks/ directory (configured in hook.yml):

     hooks:
       directory: ./hooks
     

2. PHAR Updates Breaking Hooks:

   • Problem: composer update may overwrite the PHAR, breaking custom logic.
   • Fix: Pin the PHAR version in composer.json:

     "extra": {
       "phar-captainhook": "5.6.0"
     }
     

   • Workaround: Use a local PHAR backup or fork the package.

3. Hook Conflicts:

   • Problem: Existing .git/hooks/ files are overwritten.
   • Fix: Configure CaptainHook to use a custom directory:

     hooks:
       directory: ./custom-hooks
     

   • Alternative: Merge hooks manually or use hook --skip-existing.

4. Slow Hooks in CI:

   • Problem: Hooks add significant time to CI pipelines.
   • Fix:
     • Cache results (e.g., skip tests if no files changed).
     • Use --skip in CI:

       - run: vendor/bin/hook run pre-commit --skip
       

5. Laravel-Specific Gotchas:

   • Problem: Artisan commands fail due to missing .env or config.
   • Fix: Set up hooks in a way that respects Laravel’s environment:

     hooks:
       pre-commit:
         - ". .env && php artisan test"
     

Debugging

1. Verbose Mode:

   vendor/bin/hook run pre-commit --verbose
   

   Reveals the exact commands being executed and their exit codes.

2. Dry Run:

   vendor/bin/hook run pre-commit --dry-run
   

   Lists commands without executing them.

3. Log Hook Output: Redirect output to a file:

   hooks:
     pre-commit:
       - "php artisan test --env=testing > storage/logs/hook-test.log 2>&1"
   

4. Check PHAR Integrity: Verify the PHAR isn’t corrupted:

   composer show captainhook/captainhook-phar
   

   Look for checksum mismatches or missing files.

Config Quirks

1. YAML vs. PHP Config:

   • YAML: Simpler for basic hooks (e.g., hooks.yml).
   • PHP: Better for dynamic logic (e.g., config/hook.php):

     return [
         'hooks' => [
             'pre-commit' => [
                 'commands' => function () {
                     return ['php artisan test', 'php vendor/bin/pint'];
                 },
             ],
         ],
     ];
     

2. Hook Order: Hooks run in the order defined in the config. Use comments to document dependencies:

   hooks:
     pre-commit:
       # 1. Run tests
       - "php artisan test"
       # 2. Lint code
       - "php vendor/bin/pint"
   

3. Global vs. Local Hooks:

   • Global: Install hooks in .git/hooks/ (default).
   • Local: Use a project-specific hooks/ directory:

     hooks:
       directory: ./hooks
     

Extension Points

1. Custom Hook Commands: Extend CaptainHook by creating a wrapper script:

   # hooks/custom-pre-commit.sh
   #