Weave Code
Phpstan Phpunit Laravel Package
phpstan/phpstan-phpunit
PHPStan extension for PHPUnit that improves mock object and assert type inference, supports MockBuilder and phpDoc intersections, and adds optional strict rules for more precise, framework-aware static analysis.
phpstan/phpstan-phpunit is the official PHPStan extension for PHPUnit. It teaches PHPStan to understand test doubles and assertions, so mocks expose both MockObject methods like expects() and the mocked class API through intersection types.
It also ships optional strict rules for cleaner, more meaningful assertions.
createMock(),getMockForAbstractClass(), andgetMockFromWsdl()return intersection typesMockBuilder::getMock()is supportedFoo|MockObjectin phpDoc is interpreted as an intersection type- Infers types from
assertInstanceOf,assertTrue, and similar assertions, and flags always-true/false asserts - Detects
assertSame()misuse withtrue,false,null, orcount()
Frequently asked questions about Phpstan Phpunit
- What does phpstan/phpstan-phpunit do for Laravel test suites?
- It is a PHPStan extension for PHPUnit that gives mock objects intersection types, types assert calls, and prevents undefined variable errors on TestCase. In Laravel, where feature and unit tests extend PHPUnit primitives, it makes mocks, stubs, and assertions easier for PHPStan to analyze. It also offers optional strict rules for assertSame and assertEquals usage.
- How do I install phpstan/phpstan-phpunit in a Laravel project?
- Install it as a dev dependency with composer require --dev phpstan/phpstan-phpunit. Then enable the extension through phpstan/extension-installer or include it manually in your phpstan.neon configuration. No application architecture changes are required, which keeps it suitable for existing Laravel test suites.
- Which Laravel and PHPUnit versions are compatible with phpstan/phpstan-phpunit?
- The package requires PHP 8.1 or newer and works with PHPUnit 9.x through 12.x. Laravel 10 and newer meet the PHP requirement and use PHPUnit versions covered by the extension. Legacy Laravel projects may need PHP or PHPUnit upgrades before adopting it.
- How does phpstan/phpstan-phpunit type PHPUnit mocks in PHPStan?
- Methods like createMock(), getMockForAbstractClass(), and getMockFromWsdl() return an intersection type of the mock object and the mocked class. MockBuilder::getMock() is supported too, so both PHPUnit methods such as expects() and methods from the mocked class resolve. It also interprets Foo|MockObject in PHPDoc as an intersection type rather than a union.
- How do I enable the strict assertSame and assertEquals rules?
- The strict PHPUnit rules are optional and enabled separately from the base extension. They flag patterns such as assertSame() with true, false, or null, assertSame() with count($variable), and assertEquals() or assertNotEquals() where assertSame() or assertNotSame() should be used. Enable the package's strict rules set in your PHPStan configuration when you want those checks.
- Can PHPStan autofix phpstan-phpunit errors?
- Newer versions add autofix support for two high-friction rules: AssertEmptyIsDiscouragedRule and AssertSameWithCountRule. You can run vendor/bin/phpstan analyse --fix with PHPStan 2.1 or newer on a scoped path and review the diff. Autofix does not cover every phpstan-phpunit error, so some findings still need manual changes or targeted suppression.
- Why do phpunit.assertEmpty errors remain after running phpstan --fix?
- The 2.1.1 autofix explicitly skips named arguments and unpacked arguments. Calls such as assertEmpty(value: $x) or assertSame(...$args) can therefore still report errors after --fix. Handle those manually or suppress the phpunit.assertEmpty identifier where changing the call is not desirable.
- How do I suppress a phpstan-phpunit rule in a Laravel project?
- Prefer autofix first, then suppress by error identifier, then by path, and use rule-level suppression as a last resort. For example, ignoreErrors with identifier phpunit.assertEmpty targets that specific strict rule. If a file is too complex for now, excludePaths can keep it out of analysis while you plan remediation.
- Should I run phpstan --fix in CI for Laravel tests?
- No, keep CI check-only for static analysis. Run --fix locally or in a scheduled cleanup job, review the diff in a dedicated pull request, and run it per directory or one rule at a time to avoid unreviewed mass changes. In CI, use phpstan --error-format=github so PHPStan failures are visible alongside PHPUnit failures.
- Is phpstan/phpstan-phpunit a replacement for PHPUnit or Pest?
- No. It is a static analysis extension for phpstan/phpstan, not a test runner or a replacement for PHPUnit. It helps PHPStan understand PHPUnit-based tests, including Laravel tests that extend PHPUnit classes. Pest users should verify compatibility with the PHPUnit APIs their tests rely on before enabling all strict rules.
Weaver
How can I help you explore Laravel packages today?