Composer Git Hooks Laravel Package

Getting Started

Start by installing the package via Composer:

composer require --dev brainmaestro/composer-git-hooks

Then, add a extra.git-hooks section to your composer.json to define your hooks. For example:

{
  "extra": {
    "git-hooks": {
      "pre-commit": [
        "vendor/bin/phpstan analyse src",
        "vendor/bin/php-cs-fixer fix --diff --ansi"
      ],
      "pre-push": [
        "composer test"
      ]
    }
  }
}

Run composer install (or update) — the hooks will be automatically installed into .git/hooks/. No manual setup required. First use case: ensure all developers run static analysis and linting before committing.

Implementation Patterns

• Per-project consistency: Define hooks centrally in composer.json and share them across the team. Ideal for enforcing formatting (e.g., PHP-CS-Fixer, ESLint), security checks (e.g., composer audit), or tests (e.g., PHPUnit).
• Conditional hook execution: Use Bash conditionals or if statements inside hook scripts for granular control (e.g., only lint changed files via git diff --cached --name-only).
• Modular scripts: Break long hook commands into small executable scripts (e.g., scripts/lint.sh) and reference them in composer.json for readability and reuse.
• Environments (e.g., pre-commit vs pre-push): Use different hook types to gate different stages—pre-commit for fast checks, pre-push for slower ones.
• CI complementarity: Run the same commands in CI to avoid "works on my machine" surprises—hooks catch issues early, CI enforces them strictly.

Gotchas and Tips

• Permissions: Hook files may lose execute permissions on checkout; ensure .git/hooks/* scripts are executable, or add chmod +x as a post-install script if needed.
• Hook chaining: Multiple commands in a single hook (["a", "b"]) run sequentially and fail fast—first command exit non-zero stops the rest. Use && to chain inside one string if you want group logic.
• Hooks don’t auto-upgrade: After updating extra.git-hooks, re-run composer install (or update) to refresh the hooks. Consider adding "@git-hooks" to scripts.post-install-cmd and post-update-cmd to ensure hooks stay synced.
• Overriding default hooks: Existing .git/hooks/ scripts are not overwritten—only missing or broken hooks are replaced. Use --force to override (avoid in CI).
• Team adoption: Add a note to your CONTRIBUTING.md or README that composer install is required to install hooks. Consider a pre-check in CI for missing hooks (e.g., GitHub Actions check: test -f .git/hooks/pre-commit).