Git Hooks Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Aligns with Laravel/PHP ecosystems by leveraging Composer plugins and Robo tasks, reducing friction for teams already using these tools.
  • Centralizes Git hook logic in version-controlled scripts (e.g., git-hooks/ or .git-hooks.sh), improving collaboration and reproducibility.
  • Supports modern Git (≥2.9) via core.hooksPath and falls back gracefully for older versions with symlinks/copies.
  • Decouples hook execution from Git’s un-versioned .git/hooks/ directory, enabling CI/CD-friendly workflows.

• Cons:

  • Tight coupling with Robo: The example assumes Robo for hook logic, which may not be ideal for teams not using Robo (though the package claims "Robo-independent" in v0.0.5).
  • Limited Laravel-native integration: No direct Laravel service provider or event hooks, requiring manual orchestration (e.g., calling Robo tasks from Laravel’s boot() or console commands).
  • Bash-centric: Primary hook execution relies on shell scripts (.git-hooks.sh), which may complicate Windows/Laravel Forge/Valet deployments.

Integration Feasibility

• Laravel Compatibility:
  • Works seamlessly with Composer (dev dependency) and can be triggered via post-install-cmd/post-update-cmd.
  • Can integrate with Laravel’s Artisan commands or console kernel to bridge PHP logic (e.g., run php artisan githook:pre-commit from .git-hooks.sh).
  • Supports Laravel Forge/Envoyer if hooks are version-controlled and deployed alongside code.
• Git Hook Types Supported:
  • Pre-commit, pre-push, post-merge, etc. (standard Git hooks). Custom hooks require manual configuration.
• Deployment Scenarios:
  • Shared Hosting: May fail if .git/hooks/ is not writable (symlink fallback required).
  • Docker/Kubernetes: Works if core.hooksPath is configured and volumes mount the correct directories.

Technical Risk

• High:
  • Robo Dependency: Even if "Robo-independent" in theory, the example hardcodes Robo. Teams must refactor to use PHP/Laravel alternatives (e.g., custom Artisan commands).
  • Git Version Quirks: Older Git (<2.9) may require manual symlink management or fail silently.
  • Cross-Platform Issues: Bash scripts in .git-hooks.sh may break on Windows (Git Bash required) or CI environments without shell access.
  • Performance Overhead: Composer events (post-install-cmd) add ~1–2s to deployments if hooks are complex.
• Medium:
  • Configuration Complexity: Requires composer.json setup and proper core.hooksPath permissions.
  • Debugging: Hook failures may be opaque (e.g., silent exits in .git-hooks.sh).
• Low:
  • Composer Plugin Stability: Well-tested as a plugin (CircleCI badge).
  • Version Control: Hooks are now trackable via Git.

Key Questions

1. Robo vs. Laravel:
   • How will we replace Robo tasks with Laravel-native solutions? (e.g., Artisan commands, service providers).
   • Can we abstract hook logic into a Laravel package to avoid Robo entirely?
2. Cross-Platform Support:
   • How will we handle Windows CI/CD or shared hosting where .git/hooks/ is unwritable?
   • Should we enforce symlink: true in composer.json for older Git versions?
3. Performance:
   • Are hooks a bottleneck in CI/CD? Should we lazy-load them or cache results?
4. Security:
   • How will we validate hook scripts to prevent malicious payloads in version control?
5. Laravel Integration:
   • Should hooks trigger Laravel events (e.g., git:pre-commit) for tighter coupling?
   • Can we integrate with Laravel’s app/Console/Kernel.php to run hooks on demand?

Integration Approach

Stack Fit

• Laravel/PHP Stack:
  • Composer: Native support as a dev dependency.
  • Artisan: Replace Robo tasks with Laravel commands (e.g., php artisan hook:pre-commit).
  • Service Providers: Register hook logic as Laravel services for dependency injection.
  • Events: Dispatch Laravel events from hooks (e.g., GitHookExecuted).
• Alternatives Considered:
  • Laravel Git Hooks Package: laravel-githooks (more Laravel-native but less flexible).
  • Custom Scripts: Direct .git/hooks/ management (less collaborative).
  • GitHub Actions/GitLab CI: Offload hooks to CI (but loses local pre-commit benefits).

Migration Path

1. Assessment Phase:
   • Audit existing Git hooks (.git/hooks/) and document their purpose.
   • Identify Robo dependencies and plan replacements (e.g., Artisan commands).
2. Pilot Implementation:
   • Add sweetchuck/git-hooks to composer.json (dev dependency).
   • Configure core.hooksPath (e.g., ./git-hooks) and symlink: true.
   • Migrate 1–2 critical hooks (e.g., pre-commit) to version-controlled scripts.
   • Test locally and in CI/CD (GitHub Actions, etc.).
3. Full Rollout:
   • Replace Robo tasks with Laravel commands (see Stack Fit above).
   • Update team documentation and onboarding (e.g., "Hooks are now in git-hooks/").
   • Deprecate legacy .git/hooks/ scripts post-migration.
4. Optimization:
   • Cache hook results (e.g., PHP file_put_contents for slow operations).
   • Add Laravel events for post-hook actions (e.g., GitHookFailed).

Compatibility

Sequencing

1. Pre-Migration:
   • Backup existing .git/hooks/ scripts.
   • Standardize hook naming (e.g., git-hooks/pre-commit).
2. Core Setup:
   • Install package: composer require --dev sweetchuck/git-hooks.
   • Configure composer.json:

     "extra": {
       "sweetchuck/git-hooks": {
         "core.hooksPath": "./git-hooks",
         "symlink": true
       }
     }
     

3. Hook Migration:
   • Move pre-commit to git-hooks/pre-commit (or use .git-hooks.sh).
   • Replace Robo tasks with Artisan commands (example below).
4. Laravel Integration:
   • Create a GitHookServiceProvider to register commands/events.
   • Example Artisan command:

     // app/Console/Commands/GitHookPreCommit.php
     namespace App\Console\Commands;
     use Illuminate\Console\Command;
     class GitHookPreCommit extends Command {
         protected $signature = 'hook:pre-commit';
         public function handle() {
             // Laravel logic (e.g., run tests, lint code)
             $this->info('Running pre-commit checks...');
         }
     }
     

5. Update .git-hooks.sh:

   #!/usr/bin/env bash
   : "${sghHookName:?'argument is required'}"
   : "${sghHasInput:?'argument is required'}"
   
   echo "BEGIN Git hook: ${sghHookName}"
   php artisan hook:"${sghHookName}" "${@}"
   exit $?
   

6. Testing:
   • Verify hooks trigger locally (git commit).
   • Test in CI with COMPOSER_SKIP_HOOKS=false (or similar).
7. Post-Migration:
   • Remove legacy .git/hooks/ from version control.
   • Add hooks to .gitignore (if not already present).

Operational Impact

Maintenance

• Pros:
  • Version Control: Hooks are now trackable and