Git Hooks in PHP Workflow
debt(d7/e3/b3/t5)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints note the code_pattern is 'No .git/hooks or husky config; style and type errors only caught in CI not locally' — the absence of hooks is only discovered when CI flags issues that could have been caught earlier, or during a team code review of the repo setup. Tools like captainhook/grumphp are listed but they require someone to deliberately check for their presence; there is no automatic signal that hooks are missing until problems manifest in the PR cycle.
Closest to 'simple parameterised fix' (e3). The quick_fix says 'Add a pre-commit hook that runs phpcs and phpstan --level=6' — this is more than a one-line patch (requires creating/committing a config file and integrating a tool like CaptainHook or GrumPHP), but it's a small, localised change within one component (the repo tooling configuration) that doesn't span multiple files in the application codebase itself.
Closest to 'localised tax' (b3). Per applies_to (web, cli) and tags (style, git, quality), the choice affects developer workflow and repo setup but doesn't permeate the application code. The common_mistakes around slow hooks or un-versioned hooks impose a team productivity tax, but only on the dev tooling layer — the rest of the codebase is unaffected. It's a persistent but contained configuration concern.
Closest to 'notable trap — a documented gotcha most devs eventually learn' (t5). The misconception field explicitly states the canonical wrong belief: 'Git hooks replace CI.' Developers commonly set up hooks and assume they are the authoritative quality gate, not realising hooks can be bypassed with --no-verify and run only locally. This is a well-known gotcha that most teams encounter at least once, aligning with the t5 anchor.
Also Known As
TL;DR
Explanation
Git hooks are scripts that run automatically at git lifecycle events. pre-commit: runs before the commit is created — ideal for linting and static analysis. commit-msg: validates commit message format (Conventional Commits). pre-push: runs tests before pushing. PHP workflow: use CaptainHook or a simple .git/hooks/pre-commit script to run php-cs-fixer --dry-run (fail on style violations) or php-cs-fixer (auto-fix and stage), phpstan analyse (fail on type errors), and security checks. husky manages hooks for Node projects alongside PHP.
Common Misconception
Why It Matters
Common Mistakes
- Slow hooks that take > 10 seconds — developers use --no-verify to bypass slow hooks.
- Running the full test suite in pre-commit — too slow; run only fast linting and static analysis.
- Not committing hooks to the repository — hooks in .git/hooks are not versioned; use CaptainHook or lefthook.
- No --no-verify escape hatch — emergency commits must be possible; document when to use it.
Code Examples
# .git/hooks/pre-commit — too slow, developers bypass:
#!/bin/bash
vendor/bin/phpunit # 3 minutes — developers use --no-verify
vendor/bin/phpstan analyse # OK
vendor/bin/php-cs-fixer fix # OK
# Total: 3+ minutes — nobody uses it# .git/hooks/pre-commit — fast, focused:
#!/bin/bash
set -e
# Only lint staged PHP files (fast):
STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep '\.php$')
if [ -n "$STAGED" ]; then
echo "$STAGED" | xargs vendor/bin/php-cs-fixer fix --dry-run --diff
echo "$STAGED" | xargs vendor/bin/phpstan analyse --no-progress
fi
# Total: 2-5 seconds — developers keep it enabled
# CaptainHook (committed, shared with team):
# captainhook.json: {"pre-commit": {"actions": [{"action": "php-cs-fixer"}]}}