GitHooks is a standalone CLI tool (.phar) for managing git hooks and running QA tools in PHP projects. Built with Laravel Zero.
Why GitHooks?
- Standalone binary — distributed as
.phar, so its dependencies don't interfere with your project. - Managed with Composer — no need for Phive or other tools.
- Unified configuration — one file (
githooks.php) configures all QA tools, hooks, and execution options. - Hooks, flows, jobs — map git events to groups of QA tasks with parallel execution, fail-fast, and conditional execution.
- Language agnostic — the
customjob type can run any command (eslint,prettier,composer audit, etc.), so GitHooks manages both backend and frontend QA from a single configuration.
- PHP >= 7.4
- The QA tools you want to run (phpstan, phpcs, phpmd, etc.)
composer require --dev wtyd/githooksNote: for PHP < 8.1 you must add the following events to the scripts section in your composer.json:
"scripts": {
"post-update-cmd": "Wtyd\\GitHooks\\Utils\\ComposerUpdater::phpOldVersions",
"post-install-cmd": "Wtyd\\GitHooks\\Utils\\ComposerUpdater::phpOldVersions"
}Then run composer update wtyd/githooks.
githooks conf:initIn interactive mode, GitHooks detects QA tools in vendor/bin/ and generates a tailored githooks.php. You can also use --no-interaction to copy a template.
githooks hookThis creates a .githooks/ directory with universal hook scripts and configures git config core.hooksPath .githooks. The .githooks/ directory should be committed to version control.
To automate hook installation, add it to your composer.json:
"scripts": {
"post-update-cmd": [
"vendor/bin/githooks hook"
],
"post-install-cmd": [
"vendor/bin/githooks hook"
]
}When you commit, all configured QA tools run automatically. If all checks pass, the commit proceeds. If not, you fix the code and try again.
All checks passed:
parallel_lint - OK. Time: 150ms
phpcs_src - OK. Time: 890ms
phpstan_src - OK. Time: 2.34s
phpmd_src - OK. Time: 1.23s
Results: 4/4 passed in 3.45s
Some checks failed:
parallel_lint - OK. Time: 150ms
phpcs_src - OK. Time: 890ms
phpstan_src - KO. Time: 2.34s
phpmd_src - OK. Time: 1.23s
phpstan_src:
/src/Foo.php:12 Access to undefined property $bar
/src/Foo.php:34 Method doSomething() has no return type
Results: 3/4 passed in 3.45s
githooks flow qa # Run a flow (group of jobs)
githooks flow qa --fast # Only analyze staged files (accelerable jobs)
githooks flow qa --only-jobs=phpstan_src # Run specific jobs from a flow
githooks flow qa --dry-run # Show commands without executing
githooks job phpstan_src # Run a single job
githooks job phpstan_src --format=json # JSON output for CI integrationGitHooks uses a PHP configuration file (githooks.php) with three sections: hooks, flows, and jobs.
<?php
return [
// Git hooks: map git events to flows/jobs
'hooks' => [
'command' => 'php7.4 vendor/bin/githooks', // optional: customize the hook script command
'pre-commit' => ['qa'],
'pre-push' => [
['flow' => 'full', 'only-on' => ['main', 'develop']], // only on these branches
],
],
// Flows: named groups of jobs with shared execution options
'flows' => [
'options' => ['fail-fast' => false, 'processes' => 2], // global defaults
'qa' => ['jobs' => ['phpcbf_src', 'phpcs_src', 'phpmd_src', 'parallel_lint']],
'full' => ['jobs' => ['phpstan_src', 'phpunit_all']],
],
// Jobs: individual QA tasks with declarative configuration
'jobs' => [
'phpcs_src' => [
'type' => 'phpcs',
'paths' => ['src'],
'standard' => 'PSR12',
'ignore' => ['vendor'],
// executablePath omitted: auto-detects vendor/bin/phpcs, then system PATH
],
'phpcbf_src' => [
'extends' => 'phpcs_src', // inherits paths, standard, ignore from phpcs
'type' => 'phpcbf', // overrides type
],
'phpmd_src' => [
'type' => 'phpmd',
'executablePath' => 'tools/phpmd', // explicit path when not in vendor/bin
'paths' => ['src'],
'rules' => 'cleancode,codesize,naming,unusedcode',
],
'parallel_lint' => [
'type' => 'parallel-lint',
'paths' => ['src'],
'exclude' => ['vendor'],
],
'phpstan_src' => [
'type' => 'phpstan',
'level' => 8,
'paths' => ['src'],
],
'phpunit_all' => [
'type' => 'phpunit',
'config' => 'phpunit.xml',
],
'composer_audit' => [
'type' => 'custom', // run any command
'script' => 'composer audit',
],
'eslint_src' => [
'type' => 'custom',
'executablePath' => 'npx eslint', // structured mode: executable + paths
'paths' => ['resources/js'],
'otherArguments' => '--fix',
'accelerable' => true, // opt-in: filters paths to staged files with --fast
],
],
];- Hooks map git events (
pre-commit,pre-push, etc.) to flows and jobs. Supports conditional execution by branch (only-on) and staged file patterns (only-files). - Flows are named groups of jobs with shared options (
fail-fast,processes). Reusable across hooks and directly executable from CLI. - Jobs are individual QA tasks. Each declares a
typeand its arguments. Jobs can inherit from other jobs withextends. WhenexecutablePathis omitted, GitHooks auto-detects the binary invendor/bin/.
See the wiki for the full configuration reference.
| Tool | Type | Description |
|---|---|---|
| PHP CodeSniffer | phpcs / phpcbf |
Code style checking and auto-fixing |
| PHPStan | phpstan |
Static analysis |
| PHP Mess Detector | phpmd |
Code quality rules |
| Parallel-lint | parallel-lint |
Syntax checking |
| PHPUnit | phpunit |
Unit testing |
| Psalm | psalm |
Static analysis |
| PHP Copy Paste Detector | phpcpd |
Duplicate code detection |
| Any tool | custom |
Run any command via script or executablePath + paths |
The custom type replaces the deprecated security-checker and script tools. Two modes:
- Simple:
scriptkey contains the full command ('script' => 'composer audit'). - With paths:
executablePath+paths+ optionalotherArguments. Supports--fastacceleration whenaccelerable: true.
| Command | Description |
|---|---|
githooks flow <name> |
Run a flow. Options: --fail-fast, --processes, --exclude-jobs, --only-jobs, --dry-run, --format, --fast, --monitor |
githooks job <name> |
Run a single job. Options: --dry-run, --format, --fast |
githooks hook |
Install git hooks via core.hooksPath |
githooks hook:clean |
Remove installed hooks |
githooks status |
Show hook installation status |
githooks cache:clear [jobs...] |
Clear QA tool cache files |
githooks conf:init |
Generate configuration file (interactive or template) |
githooks conf:check |
Validate configuration with deep checks |
githooks conf:migrate |
Migrate v2 config to v3 format |
githooks system:info |
Show CPU and process configuration |
See the wiki for detailed documentation.
Contributions are welcome! Send a pull request or open an issue. See the Contributing guide.
The MIT License (MIT). Please see License File for more information.