Captainhook Phar Laravel Package

Technical Evaluation

Architecture Fit

• Git Hook Orchestration: CaptainHook’s PHAR-based approach aligns perfectly with Laravel’s developer-centric workflows, providing a lightweight, dependency-free solution for enforcing pre-commit, pre-push, and post-merge validations. Its Composer integration ensures seamless adoption within Laravel’s existing toolchain (Artisan, Composer scripts).
• Laravel Synergy: While not Laravel-specific, it complements Laravel’s ecosystem by enabling:
  • Artisan Integration: Hooks can trigger Laravel commands (e.g., php artisan test, php artisan migrate:status).
  • Config-Driven Workflows: YAML/JSON configs can mirror Laravel’s config/ structure (e.g., config/hook.php).
  • CI/CD Alignment: Works natively with Laravel Forge, Envoyer, or GitHub Actions for deployment hooks.
• Isolation: PHAR encapsulation avoids polluting the global environment or requiring system-wide installs, reducing conflicts with other tools (e.g., husky, pre-commit).

Integration Feasibility

• Composer Workflow:
  • Dev Dependency: Installed via composer require --dev, keeping it out of production builds.
  • Auto-Update: PHAR updates on composer update, but version pinning is recommended for stability.
• Git Hook Placement:
  • Installs hooks in .git/hooks/ by default, which may conflict with manual hooks. Mitigation:
    • Use a custom directory (e.g., hooks/) and symlink to .git/hooks/.
    • Document hook merge strategies (e.g., "CaptainHook hooks take precedence").
• Laravel-Specific Extensions:
  • Artisan Commands: Extend Laravel’s CLI with custom commands (e.g., hook:install, hook:test) to manage hooks programmatically.
  • Service Provider: Register a HookServiceProvider to dynamically load hook configs from Laravel’s config system.
• CI/CD Pipeline:
  • GitHub Actions: Add a step to validate hooks:

    - name: Run pre-commit hooks
      run: php vendor/bin/hook run pre-commit
    

  • Parallel Execution: Run hooks in CI to catch issues early (e.g., fail fast if tests or linting fails).

Technical Risk

• PHAR Security:
  • Risk: PHAR files can execute arbitrary code. Mitigation:
    • Verify checksums via Composer’s dist config:

      "config": {
        "preferred-install": "dist",
        "checksum": {
          "captainhook/captainhook-phar": "sha256:..."
        }
      }
      

    • Restrict execution to trusted environments (e.g., dev/staging).
• Hook Conflicts:
  • Risk: Overwriting existing .git/hooks/ may break manual hooks. Mitigation:
    • Use a dedicated hooks/ directory and symlink:

      mkdir -p hooks
      ln -s hooks/pre-commit .git/hooks/pre-commit
      

    • Document conflicts in CONTRIBUTING.md.
• Deprecation:
  • Risk: Last release in 2021 with no maintenance. Mitigation:
    • Fork the repository and maintain it internally.
    • Monitor forks (e.g., php-captainhook/captainhook) for updates.
    • Evaluate alternatives (e.g., roave/infection, dealerdirect/phpcodesniffer-composer-installer) if critical.
• Laravel-Specific Gaps:
  • Risk: Limited native Laravel integration (e.g., no direct support for migrate or queue:work hooks). Mitigation:
    • Use generic hooks to trigger Laravel logic:

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

Key Questions

1. Strategic Alignment:
   • Does this fit the team’s shift-left strategy (e.g., catching issues pre-commit vs. in CI)?
   • How does it compare to existing tools (e.g., Laravel’s built-in testing, phpcs via Composer scripts)?
2. Maintenance Commitment:
   • Is the team willing to fork/maintain the package if upstream stalls?
   • What’s the SLA for hook reliability (e.g., 99% uptime for pre-commit hooks)?
3. Alternatives Assessment:
   • Custom Scripts: More control but higher maintenance.
   • Node.js Tools: husky + laravel-mix if the team uses both stacks.
   • Laravel Packages: spatie/laravel-permission for role-based hook access.
4. Performance:
   • What’s the acceptable latency for hooks (e.g., 500ms vs. 2s)?
   • Will hooks block Git operations (e.g., git commit) or run in parallel?
5. Adoption Barriers:
   • How will the team train developers on hook usage (e.g., "Why your commit was rejected")?
   • What’s the fallback if hooks fail (e.g., manual review, bypass mechanisms)?

Integration Approach

Stack Fit

• PHP/Laravel Ecosystem:
  • Pros:
    • No external dependencies (pure PHP/PHAR).
    • Integrates with Composer, Artisan, and Laravel’s config system.
    • Works in monorepos and multi-repo setups.
  • Cons:
    • Limited support for non-PHP tools (e.g., JavaScript linting).
    • No GUI: Requires CLI familiarity (mitigate with docs/tooling).
• Toolchain Compatibility:
  • Composer: Dev dependency with auto-updates (pin version for stability).
  • Git: Direct hook management (conflict with manual hooks).
  • CI/CD:
    • GitHub Actions: Validate hooks in workflows.
    • Laravel Forge/Envoyer: Deploy hooks alongside code.
  • Laravel-Specific:
    • Artisan: Extend with custom commands (e.g., hook:list).
    • Config: Load hook configs from config/hook.php.

Migration Path

1. Pilot Phase (2 Weeks):

   • Scope: Single repo (e.g., a Laravel monolith or microservice).
   • Steps:
     1. Install:

        composer require --dev captainhook/captainhook-phar
        

     2. Initialize hooks:

        vendor/bin/hook init
        

     3. Define hooks in hooks.yml:

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

     4. Test in local dev and CI.
   • Success Criteria:
     • Hooks trigger without blocking workflows.
     • No conflicts with existing .git/hooks/.

2. Gradual Rollout (4 Weeks):

   • Scope: Expand to 2–3 repos; add Laravel-specific hooks (e.g., php artisan optimize).
   • Steps:
     • Create a shared hooks.yml template for new repos.
     • Integrate with CI pipelines (e.g., fail builds on hook failures).
     • Document hook bypass procedures (e.g., --no-verify for emergencies).

3. Full Adoption (Ongoing):

   • Scope: All Laravel repos; enforce hooks in PR templates.
   • Steps:
     • Add hook validation to GitHub Actions:

       - name: Verify hooks
         run: |
           if ! php vendor/bin/hook run pre-commit; then
             echo "::error::Pre-commit hooks failed"
             exit 1
           fi
       

     • Train team on hook debugging (e.g., vendor/bin/hook debug).

Compatibility

• PHP Version: Supports 7.4+ (align with Laravel’s minimum version).
• Git Version: No constraints; assume Git 2.10+ (modern Git).
• Laravel Version: No explicit versioning, but PHAR is backward-compatible.
• Environment-Specific Hooks:
  • Use YAML/JSON configs to define environment-specific hooks:

    # hooks.yml
    hooks:
      pre-commit:
        - "php artisan test --env=testing"
      pre-push:
        - "php artisan migrate:fresh --env=staging"  # Only for staging
    

  • Dynamic Loading: Load configs via Laravel’s config() helper:

    // app/Providers/AppServiceProvider.php
    public function boot()
    {
        $hooks = config('hook.config');
        // Integrate