### CaptainHook Configuration Example

Source: https://github.com/captainhook-git/captainhook/blob/main/README.md

Example captainhook.json file demonstrating configuration for commit-msg and pre-commit hooks.

```json
{
  "commit-msg": {
    "actions": [
      {
        "action": "CaptainHook.Message.MustFollowBeamsRules"
      }
    ]
  },
  "pre-commit": {
    "actions": [
      {
        "action": "phpunit"
      },
      {
        "action": "phpcs --standard=psr12 src"
      }
    ]
  }
}
```

--------------------------------

### Install Hook Installer Plugin

Source: https://github.com/captainhook-git/captainhook/blob/main/README.md

Add the hook-installer Composer plugin to automatically run 'captainhook install' after Composer commands.

```bash
composer require --dev captainhook/hook-installer
```

--------------------------------

### Install CaptainHook Source with Composer

Source: https://github.com/captainhook-git/captainhook/blob/main/README.md

Install the CaptainHook source code and its dependencies using Composer.

```bash
composer require --dev captainhook/captainhook
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/captainhook-git/captainhook/blob/main/CONTRIBUTING.md

Run these commands after cloning the repository to set up the development environment.

```bash
composer install
```

```bash
tools/phive --home ./.phive install --trust-gpg-keys 4AA394086372C20A,31C7E470E2138192,8E730BA25823D8B5 --force-accept-unsigned
```

--------------------------------

### Configure and Install CaptainHook Hooks

Source: https://context7.com/captainhook-git/captainhook/llms.txt

Run the `configure` command to interactively generate the `captainhook.json` file, and then use the `install` command to activate the hooks in the `.git` directory.

```bash
# Interactive setup: generates captainhook.json
vendor/bin/captainhook configure

# Activate hooks in .git (must be run by each developer)
vendor/bin/captainhook install
```

--------------------------------

### CaptainHook CLI: Install Command Options

Source: https://context7.com/captainhook-git/captainhook/llms.txt

Options for the `captainhook install` command, including specifying a custom configuration path, forcing an overwrite of existing hooks, or skipping already installed hooks.

```bash
# Standard install using captainhook.json in CWD
vendor/bin/captainhook install

# Specify a custom config path
vendor/bin/captainhook install --configuration=config/captainhook.json

# Force overwrite existing hooks
vendor/bin/captainhook install --force

# Skip hooks already installed (skip confirmation prompts)
vendor/bin/captainhook install --skip-existing
```

--------------------------------

### Install Git Hooks

Source: https://github.com/captainhook-git/captainhook/blob/main/README.md

Install the configured Git hooks into your local .git directory using the CaptainHook command.

```bash
vendor/bin/captainhook install
```

--------------------------------

### Example Conditions for Actions

Source: https://context7.com/captainhook-git/captainhook/llms.txt

Demonstrates various conditions that can be applied to actions, including file type, directory, branch status, and logical combinations.

```json
{
  "pre-commit": {
    "actions": [
      {
        "action": "tools/phpcs --standard=psr12 src",
        "conditions": [
          {
            "exec": "CaptainHook.FileStaged.OfType",
            "args": ["php"]
          }
        ]
      },
      {
        "action": "yarn lint",
        "conditions": [
          {
            "exec": "CaptainHook.FileStaged.InDirectory",
            "args": ["assets/js"]
          }
        ]
      },
      {
        "action": "phpunit",
        "conditions": [
          {
            "exec": "CaptainHook.Status.OnBranch",
            "args": ["main"]
          }
        ]
      },
      {
        "action": "vendor/bin/phpstan analyse",
        "conditions": [
          {
            "exec": "CaptainHook.Logic.And",
            "args": [
              ["CaptainHook.FileStaged.OfType", ["php"]],
              ["CaptainHook.Status.OnMatchingBranch", ["#^(main|develop)$#"]]
            ]
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Install CaptainHook via Composer or Phive

Source: https://context7.com/captainhook-git/captainhook/llms.txt

Install CaptainHook as a dev dependency using Composer or with Phive. The `hook-installer` package can be added to auto-install hooks after `composer install`.

```bash
# Install as a dev dependency (source)
composer require --dev captainhook/captainhook

# Or install the PHAR build (lighter, no source dependencies)
composer require --dev captainhook/captainhook-phar

# Or with Phive
phive install captainhook

# Auto-install hooks after every `composer install` (team convenience)
composer require --dev captainhook/hook-installer
```

--------------------------------

### Install CaptainHook PHAR with Composer

Source: https://github.com/captainhook-git/captainhook/blob/main/README.md

Install the CaptainHook PHAR package using Composer for development.

```bash
composer require --dev captainhook/captainhook-phar
```

--------------------------------

### Install CaptainHook with Phive

Source: https://github.com/captainhook-git/captainhook/blob/main/README.md

Use Phive to install the CaptainHook PHAR file for managing Git hooks.

```bash
phive install captainhook
```

--------------------------------

### Implement a Timing Plugin in PHP

Source: https://context7.com/captainhook-git/captainhook/llms.txt

This plugin measures the execution time of hooks and individual actions. It requires implementing the `PluginHook` interface and uses `microtime(true)` to record start and end times.

```php
<?php
// src/Plugin/TimingPlugin.php
namespace MyApp\Plugin;

use CaptainHook\App\Config;
use CaptainHook\App\Console\IO;
use CaptainHook\App\Plugin\Hook as PluginHook;
use CaptainHook\App\Runner\Hook as RunnerHook;
use SebastianFeldmann\Git\Repository;

class TimingPlugin implements PluginHook
{
    private float $start;
    private array $actionTimes = [];

    public function configure(
        Config         $config,
        IO             $io,
        Repository     $repository,
        Config\Plugin  $plugin
    ): void {
        // called once before the hook starts
    }

    public function beforeHook(RunnerHook $hook): void
    {
        $this->start = microtime(true);
    }

    public function beforeAction(RunnerHook $hook, Config\Action $action): void
    {
        $this->actionTimes[$action->getLabel()] = microtime(true);
    }

    public function afterAction(RunnerHook $hook, Config\Action $action): void
    {
        $elapsed = round(microtime(true) - $this->actionTimes[$action->getLabel()], 3);
        // log $elapsed for this action
    }

    public function afterHook(RunnerHook $hook): void
    {
        $total = round(microtime(true) - $this->start, 3);
        // log total hook duration
    }
}

```

--------------------------------

### Implement Custom PHP Action for Jira Ticket Validation

Source: https://context7.com/captainhook-git/captainhook/llms.txt

Custom PHP actions must implement the `Action` interface. This example validates if a commit message references a Jira ticket.

```php
<?php
// src/Hook/ValidateJiraTicket.php
namespace MyApp\Hook;

use CaptainHook\App\Config;
use CaptainHook\App\Console\IO;
use CaptainHook\App\Exception\ActionFailed;
use CaptainHook\App\Hook\Action;
use SebastianFeldmann\Git\Repository;

class ValidateJiraTicket implements Action
{
    public function execute(
        Config        $config,
        IO            $io,
        Repository    $repository,
        Config\Action $action
    ): void {
        $project = $action->getOptions()->get('project', 'PROJ');
        $pattern = '#' . $project . '-[0-9]+#i';
        $msg     = $repository->getCommitMsg()->getContent();

        if (!preg_match($pattern, $msg)) {
            throw new ActionFailed(
                "Commit message must reference a $project ticket (e.g. $project-123)"
            );
        }

        $io->write("<info>Ticket reference found.</info>", true, IO::VERBOSE);
    }
}
```

```json
{
  "commit-msg": {
    "actions": [
      {
        "action": "\MyApp\Hook\ValidateJiraTicket",
        "options": { "project": "MYAPP" }
      }
    ]
  }
}
```

--------------------------------

### Configure CaptainHook

Source: https://github.com/captainhook-git/captainhook/blob/main/README.md

Run the CaptainHook executable to create the captainhook.json configuration file.

```bash
vendor/bin/captainhook configure
```

--------------------------------

### Action Settings: allow-failure and label

Source: https://context7.com/captainhook-git/captainhook/llms.txt

Shows how to configure 'allow-failure' to ignore action exit codes and 'label' to customize output display for actions.

```json
{
  "pre-commit": {
    "actions": [
      {
        "action": "phpcs --standard=psr12 src",
        "config": {
          "label": "Code style check (PSR-12)",
          "allow-failure": true
        }
      },
      {
        "action": "phpstan analyse --level=8 src",
        "config": {
          "label": "Static analysis"
        }
      }
    ]
  }
}
```

--------------------------------

### Configure PHP Syntax Linting

Source: https://context7.com/captainhook-git/captainhook/llms.txt

Runs `php -l` against all staged PHP files. Only available in `pre-commit` hooks. Custom PHP binary path can be set globally or via `run-exec`.

```json
{
  "pre-commit": {
    "actions": [
      {
        "action": "CaptainHook.Tools.PHPLint"
      }
    ]
  }
}
```

--------------------------------

### Configure Custom Settings for PHP Actions in JSON

Source: https://context7.com/captainhook-git/captainhook/llms.txt

This JSON configuration defines custom settings, including a Slack webhook URL, and enables a `post-commit` hook that uses the custom `NotifySlack` action. Custom settings are accessed via `$config->getCustomSettings()` in the action.

```json
{
  "config": {
    "custom": {
      "slack-webhook": "https://hooks.slack.com/services/XXX/YYY/ZZZ"
    }
  },
  "post-commit": {
    "enabled": true,
    "actions": [
      { "action": "\\MyApp\\Hook\\NotifySlack" }
    ]
  }
}

```

--------------------------------

### Include External Hook Definitions in JSON

Source: https://context7.com/captainhook-git/captainhook/llms.txt

This JSON configuration demonstrates how to include external hook definition files using the `includes` array. The `includes-level` setting controls the depth of nested includes.

```json
{
  "config": {
    "includes": [
      "./hooks/company-standards.json",
      "./hooks/php-quality.json"
    ],
    "includes-level": 1
  },
  "pre-commit": {
    "actions": [
      { "action": "phpunit --testsuite Unit" }
    ]
  }
}

```

--------------------------------

### Check Composer Lock File Synchronization

Source: https://context7.com/captainhook-git/captainhook/llms.txt

Verifies that composer.lock is in sync with composer.json by comparing content hashes. Fails the commit if they diverge.

```json
{
  "pre-commit": {
    "actions": [
      {
        "action": "CaptainHook.Tools.CheckComposerLockFile",
        "options": {
          "path": ".",
          "name": "composer"
        }
      }
    ]
  }
}
```

--------------------------------

### Configure CaptainHook Plugins in JSON

Source: https://context7.com/captainhook-git/captainhook/llms.txt

This JSON configuration enables custom plugins like `TimingPlugin` and the built-in `PreserveWorkingTree` plugin. Options can be passed to plugins via the `options` key.

```json
{
  "config": {
    "plugins": [
      {
        "plugin": "\\MyApp\\Plugin\\TimingPlugin",
        "options": { "logFile": "/tmp/captainhook-timing.log" }
      },
      {
        "plugin": "\\CaptainHook\\App\\Plugin\\Hook\\PreserveWorkingTree"
      }
    ]
  }
}

```

--------------------------------

### Implement a Custom PHP Action for Notifications

Source: https://context7.com/captainhook-git/captainhook/llms.txt

This custom action `NotifySlack` demonstrates how to access custom configuration values defined under `config.custom` in the CaptainHook configuration. It retrieves a Slack webhook URL and the current branch to post a notification.

```php
<?php
namespace MyApp\Hook;

use CaptainHook\App\Config;
use CaptainHook\App\Console\IO;
use CaptainHook\App\Hook\Action;
use SebastianFeldmann\Git\Repository;

class NotifySlack implements Action
{
    public function execute(
        Config        $config,
        IO            $io,
        Repository    $repository,
        Config\Action $action
    ): void {
        $custom     = $config->getCustomSettings();
        $webhookUrl = $custom['slack-webhook'] ?? '';
        $branch     = $repository->getInfoOperator()->getCurrentBranch();

        if (empty($webhookUrl)) {
            $io->write('<comment>Slack webhook not configured, skipping.</comment>');
            return;
        }

        // post to Slack...
        $io->write("<info>Notified Slack for branch $branch</info>");
    }
}

```

--------------------------------

### CaptainHook CLI: Add Action Command

Source: https://context7.com/captainhook-git/captainhook/llms.txt

Add a new action to a specified hook using the `captainhook add` command. Actions can be CLI commands or custom PHP classes.

```bash
vendor/bin/captainhook add --hook=pre-commit --action="phpcs src"

# Add a PHP class action
vendor/bin/captainhook add --hook=commit-msg \
  --action="\\MyApp\\Hook\\ValidateTicket"
```

--------------------------------

### CaptainHook CLI: Enable/Disable Hook Commands

Source: https://context7.com/captainhook-git/captainhook/llms.txt

Use `captainhook disable` and `captainhook enable` to toggle hooks without removing their configured actions.

```bash
vendor/bin/captainhook disable --hook=pre-push
vendor/bin/captainhook enable  --hook=pre-push
```

--------------------------------

### Configure Conventional Commit Validation (Beams Rules)

Source: https://context7.com/captainhook-git/captainhook/llms.txt

Validates commit messages against the 'Beams rules' including subject length, body line length, imperative mood, and no trailing period.

```json
{
  "commit-msg": {
    "actions": [
      {
        "action": "CaptainHook.Message.MustFollowBeamsRules",
        "options": {
          "subjectLength": 50,
          "bodyLineLength": 72,
          "checkImperativeBeginningOnly": false
        }
      }
    ]
  }
}
```

--------------------------------

### Enforce PHP Test Coverage Threshold

Source: https://context7.com/captainhook-git/captainhook/llms.txt

Ensures project test coverage meets a minimum threshold. Can use PHPUnit directly or a Clover XML report.

```json
{
  "pre-commit": {
    "actions": [
      {
        "action": "\CaptainHook\App\Hook\PHP\Action\TestCoverage",
        "options": {
          "minCoverage": 80,
          "cloverXml": "build/logs/clover.xml"
        }
      }
    ]
  }
}
```

--------------------------------

### Limit Staged File Size

Source: https://context7.com/captainhook-git/captainhook/llms.txt

Checks all staged files against a maximum file size. Units can be B, K, M, G, T, P.

```json
{
  "pre-commit": {
    "actions": [
      {
        "action": "\CaptainHook\App\Hook\File\Action\MaxSize",
        "options": {
          "maxSize": "2M"
        }
      }
    ]
  }
}
```

--------------------------------

### Configure Rule-Based Commit Message Validation

Source: https://context7.com/captainhook-git/captainhook/llms.txt

Applies a configurable list of individual rule classes to the commit message, such as checking for non-empty subjects or limiting line lengths.

```json
{
  "commit-msg": {
    "actions": [
      {
        "action": "\CaptainHook\App\Hook\Message\Action\Rules",
        "options": [
          "\CaptainHook\App\Hook\Message\Rule\MsgNotEmpty",
          "\CaptainHook\App\Hook\Message\Rule\CapitalizeSubject",
          "\CaptainHook\App\Hook\Message\Rule\NoPeriodOnSubjectEnd",
          "\CaptainHook\App\Hook\Message\Rule\SeparateSubjectFromBodyWithBlankLine",
          ["\CaptainHook\App\Hook\Message\Rule\LimitSubjectLength", [72]],
          ["\CaptainHook\App\Hook\Message\Rule\LimitBodyLineLength", [120]]
        ]
      }
    ]
  }
}
```

--------------------------------

### Configure Commit Message Regex Validation

Source: https://context7.com/captainhook-git/captainhook/llms.txt

Enforces that the commit message matches a given regular expression. Skips merge commits automatically.

```json
{
  "commit-msg": {
    "actions": [
      {
        "action": "CaptainHook.Message.MustMatchRegex",
        "options": {
          "regex": "#^(feat|fix|chore|docs|refactor)(\(.+\))?: .+#",
          "error": "Commit message must follow Conventional Commits format",
          "success": "Conventional commit format matched: %s"
        }
      }
    ]
  }
}
```

--------------------------------

### Detect Secrets in Diffs

Source: https://context7.com/captainhook-git/captainhook/llms.txt

Scans added lines in staged files or pushed commits for secrets using regex patterns and/or Shannon entropy analysis. Supports built-in suppliers and entropy-based detection for specific file types.

```json
{
  "pre-commit": {
    "actions": [
      {
        "action": "\CaptainHook\App\Hook\Diff\Action\BlockSecrets",
        "options": {
          "blocked": [
            "#password\s*=\s*['"][^'"]+['"]#i",
            "#api_key\s*=\s*['"][^'"]+['"]#i"
          ],
          "allowed": [
            "#password\s*=\s*['"]changeme['"]#i"
          ],
          "entropyThreshold": 3.5,
          "suppliers": ["default"]
        }
      }
    ]
  }
}
```

--------------------------------

### Enforce Branch Naming Convention

Source: https://context7.com/captainhook-git/captainhook/llms.txt

Validates that the current branch name matches a specified regex. Applicable to pre-commit, pre-push, and post-checkout hooks.

```json
{
  "pre-commit": {
    "actions": [
      {
        "action": "CaptainHook.Branch.EnsureNaming",
        "options": {
          "regex": "#^(feature|bugfix|hotfix|release)/[A-Z]+-[0-9]+-[a-z0-9-]+$#",
          "error": "Branch name must follow: <type>/TICKET-123-short-description",
          "success": "Branch name is valid."
        }
      }
    ]
  }
}
```

--------------------------------

### Prevent Push of Fixup/Squash Commits

Source: https://context7.com/captainhook-git/captainhook/llms.txt

Prevents pushing 'fixup!' or 'squash!' commits to protected branches. Only applicable in pre-push hooks.

```json
{
  "pre-push": {
    "actions": [
      {
        "action": "CaptainHook.Branch.PreventPushOfFixupAndSquashCommits",
        "options": {
          "blockFixupCommits": true,
          "blockSquashCommits": true,
          "protectedBranches": ["main", "master", "develop"]
        }
      }
    ]
  }
}
```

--------------------------------

### Display Commit Message Notifications

Source: https://context7.com/captainhook-git/captainhook/llms.txt

Reads incoming commits on post-checkout, post-merge, or post-rewrite and displays developer notifications embedded in commit messages with the 'git-notify:' prefix.

```json
{
  "post-merge": {
    "actions": [
      {
        "action": "\CaptainHook\App\Hook\Notify\Action\Notify",
        "options": {
          "prefix": "git-notify:"
        }
      }
    ]
  }
}
```

--------------------------------

### Auto-inject Issue Key into Commit Message

Source: https://context7.com/captainhook-git/captainhook/llms.txt

Extracts an issue key from the branch name and injects it into the commit message. Useful for `prepare-commit-msg` or `commit-msg` hooks.

```json
{
  "prepare-commit-msg": {
    "actions": [
      {
        "action": "CaptainHook.Message.InjectIssueKeyFromBranch",
        "options": {
          "regex": "#([A-Z]+-[0-9]+)#i",
          "into": "subject",
          "mode": "prepend",
          "pattern": "[$1] ",
          "modify": "uppercase",
          "force": false
        }
      }
    ]
  }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.