Hook Installer Laravel Package

Technical Evaluation

Architecture Fit

• Git Hook Automation: The package integrates seamlessly with CaptainHook, a PHP-based git hook manager, automating hook activation via Composer—a natural fit for Laravel projects where dependency management is centralized.
• Pre-commit/Pre-push Enforcement: Aligns with Laravel’s CI/CD and quality gates (e.g., PHPStan, Pest) by ensuring hooks run locally before code reaches shared environments.
• Composer Plugin Model: Leverages Composer’s lifecycle events (post-install, post-update), reducing friction for developers accustomed to Laravel’s dependency workflow.

Integration Feasibility

• Low Coupling: Operates at the git hook layer, not the Laravel framework itself, minimizing risk of conflicts with core Laravel components.
• Dev-Only Dependency: Marked as require-dev, ensuring it doesn’t bloat production builds.
• CaptainHook Dependency: Requires CaptainHook (v1.0+) to be pre-installed, adding a minor setup overhead but no architectural constraints.

Technical Risk

• PHP Version Lock: Requires PHP 8.0+, which may exclude legacy Laravel projects (e.g., LTS 7.x). Mitigation: Validate compatibility with target PHP versions early.
• Hook Bypass Risk: The README warns hooks can be bypassed (git commit --no-verify). Mitigate by:
  • Enforcing pre-commit hooks in CI (e.g., GitHub Actions) to reject unchecked commits.
  • Documenting the risk in team onboarding.
• Configuration Complexity: Custom paths/execs for CaptainHook may require composer.json tweaks, adding minor maintenance overhead.

Key Questions

1. Hook Scope: Will hooks be project-specific (e.g., Laravel-specific linting) or shared across monorepos?
2. CI Redundancy: How will CI validate hooks if developers bypass them locally?
3. Performance Impact: Could hook execution slow down git operations? Benchmark with critical paths (e.g., git commit).
4. Team Adoption: Are developers comfortable with PHP-based hooks, or should alternatives (e.g., Husky) be considered?
5. Rollback Plan: How will hooks be disabled if they cause issues (e.g., disable-plugin: true in composer.json)?

Integration Approach

Stack Fit

• Laravel Ecosystem: Ideal for projects using:
  • PHP 8.0+ (Laravel 8+).
  • Composer for dependency management.
  • Git for version control (universal).
• Alternatives Considered:
  • Husky: JavaScript-based, may require additional tooling (e.g., npx).
  • Pre-commit Framework: Overkill for Laravel’s PHP-centric workflow.
• Synergy: Pairs well with Laravel’s Pint, PHPStan, or Pest for pre-commit checks.

Migration Path

1. Prerequisite Setup:
   • Install CaptainHook via Composer:

     composer require --dev captainhook/captainhook
     

   • Configure hooks in captainhook.json (e.g., linting, tests).
2. Plugin Installation:
   • Add hook-installer:

     composer require --dev captainhook/hook-installer
     

   • Verify composer.json includes:

     "extra": {
       "captainhook": {
         "config": "captainhook.json",
         "only-enabled": true
       }
     }
     

3. Validation:
   • Test composer install/update triggers hook setup.
   • Verify hooks run via git commit (check .git/hooks/).

Compatibility

• Laravel Versions: Tested with Laravel 8+ (PHP 8.0+). For Laravel 7, upgrade PHP or use a legacy CaptainHook version.
• Git Clients: Works with all Git clients (CLI, GitHub Desktop, etc.), but CLI is recommended for debugging.
• CI/CD: Ensure CI pipelines run hooks via git commit or explicitly trigger them (e.g., GitHub Actions workflows).

Sequencing

1. Development Phase:
   • Install CaptainHook → Configure hooks → Add hook-installer.
2. Team Rollout:
   • Document hook purpose and bypass risks.
   • Train developers on troubleshooting (e.g., captainhook debug).
3. Production:
   • Monitor hook failures in CI (e.g., failed pre-commit hooks).
   • Gradually enforce via CI (e.g., reject PRs with bypassed hooks).

Operational Impact

Maintenance

• Composer Dependency: Updates handled via composer update. Monitor CaptainHook releases for breaking changes.
• Hook Updates: Modify captainhook.json and run composer update to reinstall hooks.
• Debugging: Use captainhook debug or check .git/hooks/ for errors. Log hook output to a file for visibility:

  "extra": {
    "captainhook": {
      "log-file": "storage/logs/captainhook.log"
    }
  }
  

Support

• Developer Onboarding: Add a CONTRIBUTING.md section on hook requirements.
• Common Issues:
  • Hooks Not Running: Verify composer install executed (check .git/hooks/).
  • Permission Errors: Ensure hooks are executable (chmod +x .git/hooks/*).
  • PHP Path Issues: Configure exec in composer.json if PHP isn’t in PATH.
• Escalation Path: For critical hook failures, provide a composer.json flag to disable hooks temporarily:

  "extra": { "captainhook": { "disable-plugin": true } }
  

Scaling

• Monorepos: Configure per-project captainhook.json or use a shared config with exec pointing to a central binary.
• Performance:
  • Hook Complexity: Avoid heavy operations (e.g., full test suites) in pre-commit hooks.
  • Parallelization: Use CaptainHook’s parallel option for independent hooks.
• CI Bottlenecks: Offload hook execution to CI if local runs are too slow (e.g., run hooks only on git push).

Failure Modes

Ramp-Up

• Pilot Phase:
  • Enable hooks for a subset of developers.
  • Monitor hook-related tickets (e.g., blocked commits).
• Training:
  • Workshop: Demo hook setup and debugging.
  • Cheat Sheet: Quick reference for common commands (e.g., captainhook list).
• Metrics:
  • Track hook success rate (e.g., % of commits triggering hooks).
  • Measure CI failures due to bypassed hooks.
• Feedback Loop: Survey team on usability and pain points (e.g., hook complexity).