README

1. Wtyd/GitHooks

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 custom job type can run any command (eslint, prettier, composer audit, etc.), so GitHooks manages both backend and frontend QA from a single configuration.

2. Requirements

• PHP >= 7.4
• The QA tools you want to run (phpstan, phpcs, phpmd, etc.)

3. Install

1. Install GitHooks as a dev dependency:

composer require --dev wtyd/githooks

Note: 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.

2. Initialize the configuration file:

githooks conf:init

In 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.

3. Install the git hooks:

githooks hook

This 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"
    ]
}

4. Usage

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

Running manually

githooks flow qa                          # Run a flow (group of 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 integration

5. Configuration

GitHooks 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',
        ],
    ],
];

Key concepts

• 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 type and its arguments. Jobs can inherit from other jobs with extends. When executablePath is omitted, GitHooks auto-detects the binary in vendor/bin/.

See the wiki for the full configuration reference.

6. Supported Tools

The custom type replaces the deprecated security-checker and script tools. Use it for composer audit, eslint, php-cs-fixer, or any other command.

7. Commands

See the wiki for detailed documentation.

8. Contributing

Contributions are welcome! Send a pull request or open an issue. See the Contributing guide.

9. License

The MIT License (MIT). Please see License File for more information.