rasuvaeff / understudy-phpstan
PHPStan extension for the understudy test double library: matcher-aware specification closures and misuse rules
Maintainers
Requires
- php: 8.3 - 8.5
- nikic/php-parser: ^5.0
- phpstan/phpstan: ^2.2.2
- rasuvaeff/understudy: ^0.1 || ^0.2 || ^0.3
Requires (Dev)
- ergebnis/composer-normalize: ^2.51
- friendsofphp/php-cs-fixer: ^3.95
- infection/infection: ^0.33
- maglnet/composer-require-checker: ^4.17
- rasuvaeff/rector-named-literals: ^1.0
- rector/rector: ^2.4
- roave/backward-compatibility-check: ^8.0
- testo/bridge-infection: ^0.1.6
- testo/testo: ^0.10.39
- vimeo/psalm: ^6.16
This package is auto-updated.
Last update: 2026-08-27 17:55:42 UTC
README
PHPStan extension for understudy.
Using an AI coding assistant? Point it at llms.txt.
Requirements
- PHP 8.3 - 8.5
phpstan/phpstan^2.2.2rasuvaeff/understudy^0.1
Installation
composer require --dev rasuvaeff/understudy-phpstan
With phpstan/extension-installer that is all. Without it, include the extension yourself:
includes: - vendor/rasuvaeff/understudy-phpstan/extension.neon
What it does
understudy specifies a call by making it inside a closure:
when(fn () => $repository->find(Arg::int(min: 1)))->returns($book);
Four things about that line are invisible to PHPStan on its own, and this extension is those four things.
1. A matcher fits whatever the contract declares
Arg::int() is declared mixed, because a matcher has to be passable
wherever a contract declares anything at all. At level 9 and above PHPStan
reports it as Parameter #1 $id … expects int, mixed given — correct about
the type, wrong about the code.
The extension types every matcher as never, the bottom type, which every
parameter accepts. Nothing is suppressed. A wrong argument beside a
matcher, a method the double does not have, the statements around the
closure — all keep their reports:
when(fn () => $repository->rename(Arg::any(), 'not an int')); // ^^^^^^^^^^^^ still reported when(fn () => $repository->missing(Arg::any())); // ^^^^^^^ still reported
Below level 9 there is nothing to fix here — PHPStan does not check mixed
against a declared parameter — and the rest of the extension works at every
level.
2. returns() is checked against the method being specified
The core declares when(): WhenBuilder<mixed>, and it has no choice: which
method is being specified is known only from the closure. The extension fills
the template parameter in, and PHPStan does the rest:
when(fn () => $gate->open(1))->returns('yes'); // Parameter #1 ...$values of method WhenBuilder<bool>::returns() expects bool, string given.
3. wire() has the shape of the class it wired
$wired = Understudy::wire(Checkout::class); $wired['doubles']['repository']; // Offset 'repository' does not exist on // array{books: BookRepository, clock: Clock}. $wired['doubles']['clock']->tick(); // Call to an undefined method Clock::tick().
4. Specifications that cannot work are reported
Each of these has a runtime counterpart — the engine throws, or the expectation never matches. Reporting them statically buys the one thing runtime cannot: a specification that can never match is exactly the mistake a green suite hides.
| Identifier | Reported when |
|---|---|
understudy.closure |
The closure specifies nothing, makes more than one call, or calls a static method a double cannot intercept |
understudy.cardinality |
times(5, 2), a negative bound, verify(…, never: true, times: 3), times beside a minimum |
understudy.matcher |
A matcher whose kind the parameter can never accept: Arg::int() where a string is declared |
understudy.returns |
returns() on a method declared void, where no value is ever observed |
understudy.matcherLeak |
A matcher written outside a specification, where it reaches the code as a value |
The rules are silent whenever they are not sure. A refined parameter type —
non-empty-string, an int range — answers "maybe" to its plain kind, and a
matcher can produce a value that fits it, so nothing is reported. A false
accusation costs more than a missed one here, because the engine still
catches at runtime what the extension misses.
To silence one of them, use its identifier:
parameters: ignoreErrors: - identifier: understudy.matcherLeak
Why understudy.matcherLeak exists
Typing every matcher as never is what lets one stand in for a typed
parameter, and it does so everywhere — including in a real call:
$repository->find(Arg::int()); // not a specification: the matcher is the argument
Without a rule for it the extension would be weaker than no extension for that mistake, because PHPStan would otherwise have reported the argument itself. Saying it directly is also better than the type error it replaces: at runtime the matcher reaches the code as a sentinel object, and the failure it eventually causes names neither the matcher nor the line.
Security
The extension runs inside PHPStan, reads source and reflection, and reports. It executes no code from the project under analysis and writes nothing.
Examples
See examples/README.md. The executable demonstration is
the set of fixture projects under tests/Integration/Fixtures, each analysed
by a real PHPStan process as part of composer build — including a control
run with the extension switched off, which is what tells a working extension
apart from one that loads and does nothing.
The understudy family
| Package | What it is |
|---|---|
| rasuvaeff/understudy | The engine: doubles, matchers, expectations, verification. |
| rasuvaeff/understudy-testo | Testo adapter — verification and reset around every test. |
| rasuvaeff/understudy-phpunit | PHPUnit and Pest adapter — the same, through a trait. |
| rasuvaeff/understudy-psalm | Psalm plugin — matcher-aware specifications and misuse diagnostics. |
| rasuvaeff/understudy-phpstan (this package) | PHPStan extension — the same for PHPStan, plus its own rules. |
Development
make build # validate + normalize + require-checker + cs + psalm + test + integration make test # unit suite make test-coverage # unit suite with coverage make mutation # mutation testing make release-check # build + rector + bc-check + mutation
License
BSD-3-Clause. See LICENSE.md.