Phpstan Webmozart Assert Laravel Package

Getting Started

Begin by installing the package with Composer as a development dependency:

composer require --dev phpstan/phpstan-webmozart-assert

If you use phpstan/extension-installer, no further configuration is needed—the extension registers automatically. Otherwise, manually include it in your PHPStan config (phpstan.neon):

includes:
    - vendor/phpstan/phpstan-webmozart-assert/extension.neon

Your first use case: enforce non-nullability and type precision after assertions. For example, after Assert::integer($a), PHPStan now knows $a is definitely an int, not ?int—preventing false positives in strict comparisons like $a === 10.

Implementation Patterns

• Type Narrowing: Use assertions at function/method boundaries or early validation points. Combine with nullOr* and all* prefixes for flexible validation:

  Assert::allInteger($ids); // $ids is narrowed to non-empty list<int> if non-empty
  Assert::nullOrString($name); // $name narrowed to string|null
  

• Array Assertions: Use isList, isNonEmptyList, isMap, and all* methods to refine array shapes:

  Assert::isNonEmptyList($items); // $items is non-empty list<any>
  Assert::allStringNotEmpty($strings); // $strings is array<string>
  

• Object & Class Assertions: Strengthen object type safety with isInstanceOf, classExists, interfaceExists:

  Assert::isInstanceOf($obj, SomeInterface::class); // $obj is typed as SomeInterface
  Assert::interfaceExists($interface); // Later `new $interface()` becomes safe if checked first
  

• String Assertions with Type Refinement: Pair with length/string-content checks to get precise types:

  Assert::minLength($s, 1); // $s becomes non-empty-string
  Assert::email($email); // $s refined to email-string
  

Gotchas and Tips

• Version Mismatch Pitfall: Ensure phpstan/phpstan and phpstan/phpstan-webmozart-assert versions are compatible (e.g., PHPStan 2.x requires extension ≥2.0). Check the changelog for breaking changes on major version bumps.
• Non-deterministic narrowing: Some assertions don’t narrow to exactly the assert name—e.g., Assert::numeric() doesn’t narrow to numeric-string, but to int|float|string. Check the actual supported type specs in the README for precision.
• Key existence assertions: keyExists() and keyNotExists() narrow associative array access in later code—use them before array index access to silence offset errors.
• Performance: While fast, the extension adds minimal overhead. For large codebases, limit analysis scope to files: or paths: to keep CI fast.
• Extension Points: Though not extensible yet, new methods are added regularly (e.g., interfaceExists, methodExists, propertyExists in recent releases). Watch releases for emerging coverage gaps you may need to validate manually—or contribute back!