phpstan-diff

Run PHPStan and show only the errors on lines you changed relative to a base branch (default trunk) — instead of being buried under every pre-existing error in the codebase. Handy when you run PHPStan at a stricter level: locally than the project's committed baseline.

There is no native "diff mode" in PHPStan itself — its baseline feature is a snapshot, not a git diff. (The closest off-the-shelf alternative is reviewdog with an errorformat, but that's a Go binary.) This is a small self-contained pair of scripts:

git clone <this repo> ~/repos/phpstan-diff
ln -s ~/repos/phpstan-diff/bin/phpstan-diff ~/bin/phpstan-diff   # or add bin/ to $PATH

Requirements: bash, git, php (CLI), and PHPStan reachable from the project directory (see Locating PHPStan below).

Run it from the project root, just like phpstan analyse:

phpstan-diff                                  # analyse the whole configured project, show errors on lines changed vs trunk
phpstan-diff --changed                         # faster: only run PHPStan on the .php files that changed vs trunk
phpstan-diff --changed --exclude=tests         # the changed files, minus anything under tests/
phpstan-diff --changed --include=src           # only changed files under src/
phpstan-diff -- src/wp-includes/rest-api.php   # restrict PHPStan (and the diff) to given paths
phpstan-diff --base=6.7-branch                 # diff against a different base ref
phpstan-diff --staged                          # like the default, but exclude unstaged edits (committed + staged vs trunk)
phpstan-diff --staged --base=HEAD              # only the staged changes (pre-commit-hook scope)
phpstan-diff --format=json | jq '.files | keys'

Options:

• --base=<ref> — base ref to diff against. Default: $PHPSTAN_DIFF_BASE or trunk.
• --staged — diff the staged snapshot (the git index) against the base instead of the working tree: errors on committed + staged changes, with unstaged edits ignored. Add --base=HEAD to narrow it to staged changes only (pre-commit-hook scope). (PHPStan still analyses the working tree, not the staged blob.)
• --changed — when no paths are given, only run PHPStan on the .php files that differ from the base. Much faster for PR review; may miss errors that a change introduces in other files.
• --include=<glob> — keep only files matching this repo-relative path or glob, intersected with the files that actually changed. Repeatable (a file is kept if it matches any --include). A bare directory matches everything under it (--include=src ⇒ src/Foo.php); globs work too (--include='src/*', *.php), and * may span /.
• --exclude=<glob> — drop files matching this repo-relative path or glob (--exclude=tests). Repeatable; applied after --include, and an exclude wins over an include. With --changed, excluded files aren't handed to PHPStan at all, so the run is faster too.
• --format=table (default) | --format=json — json emits the filtered PHPStan JSON document (same shape as --error-format=json, with non-changed files/messages removed).

What counts as a "changed line": every line that differs between git merge-base <base> HEAD and your working tree — i.e. your branch commits plus staged and unstaged edits. With --staged, the comparison is against the git index rather than the working tree, so unstaged edits drop out (committed + staged only); adding --base=HEAD on top of that leaves just the staged changes.

Exit status: 1 if any errors remain after filtering, 0 if none, 2 on internal errors (PHPStan didn't produce JSON, not a git repo, bad ref, …).

bin/phpstan-diff figures out how to run PHPStan, in this order:

1. $PHPSTAN_DIFF_ANALYSE_CMD if set — used verbatim, our extra args appended. E.g. PHPSTAN_DIFF_ANALYSE_CMD='composer phpstan --' or PHPSTAN_DIFF_ANALYSE_CMD='vendor/bin/phpstan analyse -c phpstan.neon'.
2. composer phpstan -- if Composer reports a phpstan script.
3. vendor/bin/phpstan analyse --memory-limit=2G (honours a custom Composer bin-dir).
4. A globally-installed phpstan analyse --memory-limit=2G.
5. Otherwise it errors and tells you to install PHPStan or set PHPSTAN_DIFF_ANALYSE_CMD.

This means it picks up whatever config composer phpstan already uses — including a local stricter phpstan.neon that overrides phpstan.neon.dist.

Drop this in .git/hooks/pre-commit (chmod +x it) to block commits that introduce errors on the lines being committed. It only checks staged .php files, never touches your working tree, and is bypassable with git commit --no-verify (or disabled with PHPSTAN_DIFF_PRECOMMIT_SKIP=1):

#!/usr/bin/env bash
set -euo pipefail
[ -n "${PHPSTAN_DIFF_PRECOMMIT_SKIP:-}" ] && exit 0

if command -v phpstan-diff >/dev/null 2>&1; then
	phpstan_diff="$(command -v phpstan-diff)"
elif [ -x "$HOME/repos/phpstan-diff/bin/phpstan-diff" ]; then
	phpstan_diff="$HOME/repos/phpstan-diff/bin/phpstan-diff"
else
	echo "pre-commit: phpstan-diff not found — skipping PHPStan check." >&2
	exit 0
fi

files=()
while IFS= read -r f; do
	[ -n "$f" ] && files+=("$f")
done < <(git diff --cached --name-only --diff-filter=ACMR -- '*.php')
[ "${#files[@]}" -eq 0 ] && exit 0

# phpstan-diff analyses files on disk and maps results onto the staged hunks; if
# a staged file also has unstaged edits, that mapping is approximate — warn only.
git diff --quiet -- "${files[@]}" || \
	echo "pre-commit: note — some staged files have unstaged changes; line mapping is approximate." >&2

# --base=HEAD scopes the diff to just the staged changes; without it, --staged
# would also report on changes committed earlier in the branch.
exec "$phpstan_diff" --staged --base=HEAD -- "${files[@]}"

Tell Claude: "to check PHPStan, run phpstan-diff --changed and only act on what it prints — those are the errors this branch introduced." (You may want to add that to a project note / Claude memory so it's used automatically.)

• Messages with no line, or a line outside every changed hunk (some file-level errors like "class not found"), are dropped.
• Truly untracked files aren't part of any diff, so PHPStan errors in them are dropped — git add them (or commit) to have them considered.
• Path quoting: paths with unusual characters in git diff headers may not be matched perfectly.
• The table output approximates phpstan analyse's table; it isn't pixel-perfect and doesn't emit editor hyperlinks (but relative path:line strings are still clickable in most IDE terminals).

This tool (both bin/ scripts and this README) was written by Claude Code using the Claude Opus 4.7 (1M context) model (claude-opus-4-7[1m]), from the prompt below, then reviewed and verified against a real repository.

MIT © Weston Ruter