PHPackages                             wtyd/githooks - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Testing & Quality](/categories/testing)
4. /
5. wtyd/githooks

ActiveLibrary[Testing & Quality](/categories/testing)

wtyd/githooks
=============

Manage git hooks in a simple and sophisticated way.

v3.6.0(2w ago)924.3k—6.7%MITPHPPHP >=7.4CI passing

Since Dec 3Pushed 1w ago4 watchersCompare

[ Source](https://github.com/Wtyd/githooks)[ Packagist](https://packagist.org/packages/wtyd/githooks)[ RSS](/packages/wtyd-githooks/feed)WikiDiscussions master Synced 2d ago

READMEChangelog (10)Dependencies (73)Versions (71)Used By (0)

 [![](https://camo.githubusercontent.com/8af2f7fb7b2cdb28bcea2f1cfd78a3da13321f682b601845fcd5e6c4d515813d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6173742d636f6d6d69742f577479642f676974686f6f6b73)](https://github.com/Wtyd/githooks/commits/ "Last Commit") [![](https://camo.githubusercontent.com/ec8dd31c7da65619d45b30067fcedd52d8691fceb39b161e3aa42a05c8913b1a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f577479642f676974686f6f6b73)](https://github.com/Wtyd/githooks/issues "Open Issues") [![](https://camo.githubusercontent.com/4130f2665fd07850b5463dd68af466ab4cfba84d3cb5cfa3ed4eea3b17ef7649/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f577479642f676974686f6f6b73)](https://github.com/Wtyd/githooks/blob/master/LICENSE "License") [![PHP Versions Supported](https://camo.githubusercontent.com/17ec4fe5257914438d79bcf349d23151e981e4dce70ffb630552a46d21d70a75/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d372e34253230746f253230382e352d3737376262332e7376673f6c6f676f3d706870266c6f676f436f6c6f723d7768697465266c6162656c436f6c6f723d353535353535)](#2-requirements "PHP Versions Supported") [![](https://camo.githubusercontent.com/66b29284c4e11f77c5ebedce6e311fa277408ccf195536fb8849654062b0369e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f577479642f676974686f6f6b73)](https://camo.githubusercontent.com/66b29284c4e11f77c5ebedce6e311fa277408ccf195536fb8849654062b0369e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f577479642f676974686f6f6b73)

 [![](https://github.com/Wtyd/githooks/workflows/Code Analysis/badge.svg)](https://github.com/Wtyd/githooks/actions?query=workflow%3A%22Code Analysis%22 "Build") [![](https://github.com/Wtyd/githooks/workflows/Main Tests/badge.svg)](https://github.com/Wtyd/githooks/actions?query=workflow%3A%22Main Tests%22 "Build") [![](https://github.com/Wtyd/githooks/workflows/Schedule CI/badge.svg)](https://github.com/Wtyd/githooks/actions?query=workflow%3A%22Schedule CI%22 "Build")

1. Wtyd/GitHooks
================

[](#1-wtydgithooks)

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
===============

[](#2-requirements)

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

3. Install
==========

[](#3-install)

#### 1. Install GitHooks as a dev dependency:

[](#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:

[](#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:

[](#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
========

[](#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

[](#running-manually)

```
githooks flow qa                                       # Run a flow (group of jobs)
githooks flow qa --fast                                # Only staged files (accelerable jobs)
githooks flow qa --fast-branch                         # Only files changed vs the base branch
githooks flow qa --fast-dirty                          # Unified working tree (ideal for AI agents)
githooks flow qa --fast-dirty --format=json --no-reports  # AI-agent friendly: clean JSON, no side-effect files
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
================

[](#5-configuration)

GitHooks uses a PHP configuration file (`githooks.php`) with three sections: **hooks**, **flows**, and **jobs**.

```