ntzrbtr / captainhook-phpstan

v1.0.0 2026-10-14 10:02 UTC

Requires

• php: ^7.4|^8.0
• captainhook/captainhook: ^5.18

Requires (Dev)

• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^9.6

Suggests

• phpstan/phpstan: Required to actually run the analysis

MIT

• Thomas Off

• git
• static analysis
• hooks
• pre-commit
• PHPStan
• captainhook

Published on Packagist.org on 2026-10-14 10:07 UTC

README

CaptainHook action for the pre-commit hook that runs PHPStan only on staged PHP files the project's PHPStan configuration actually covers.

The action asks PHPStan itself for the resolved configuration (phpstan dump-parameters --json), so paths, excludePaths (including wildcards), includes and placeholders such as %currentWorkingDirectory% behave exactly as in a full phpstan analyse run. No per-project directory lists are needed in captainhook.json.

Installation

composer require --dev ntzrbtr/captainhook-phpstan

Configuration

{
    "pre-commit": {
        "enabled": true,
        "actions": [
            {
                "action": "\\Netzarbeiter\\CaptainHookPhpstan\\Action\\AnalyseStagedFiles"
            }
        ]
    }
}

Optional settings:

{
    "action": "\\Netzarbeiter\\CaptainHookPhpstan\\Action\\AnalyseStagedFiles",
    "options": {
        "phpstan": "vendor/bin/phpstan",
        "configuration": "phpstan.neon",
        "memory-limit": "1G"
    }
}

Option	Default	Meaning
phpstan	vendor/bin/phpstan	PHPStan executable
configuration	PHPStan's own lookup	Passed as --configuration
memory-limit	PHPStan default	Passed as --memory-limit

Behaviour

• Considers added, copied, modified and renamed *.php files in the index.
• Does nothing if none of them is covered by paths or all are excluded.
• Fails the commit with PHPStan's output if errors are found.
• Note: PHPStan analyses the files in the working tree, not the staged content. Partially staged files are checked in their current working tree state.

Requirements

• PHP 7.4 or newer
• CaptainHook 5.18 or newer
• PHPStan 2.x, or a 1.x release that has the dump-parameters command

Development

composer install
vendor/bin/phpunit
vendor/bin/phpstan analyse

Releasing

1. Move the entries under [Unreleased] in CHANGELOG.md to a new version section.
2. Commit, then tag and push: git tag v1.2.3 && git push origin v1.2.3
3. The release workflow creates the GitHub release with the changelog entry as notes; Packagist picks up the new tag automatically.

License

MIT, see LICENSE.