Phpstan Beberlei Assert Laravel Package

Getting Started

1. Install the package via Composer: composer require --dev phpstan/phpstan-beberlei-assert
2. Enable the extension in your phpstan.neon config:

   extends:
     - vendor/phpstan/phpstan-beberlei-assert/extension.neon
   

3. Start using beberlei/assert in your code: the extension automatically picks up Assert::*() calls (e.g., Assert::string($input)) and informs PHPStan of the narrowed type.

👉 First use case: Wrap potentially mixed/array|object inputs with assertions (e.g., Assert::keyExists($data, 'user_id')) — PHPStan will then treat $data['user_id'] as non-nullable and strongly typed after the assertion.

Implementation Patterns

• Type narrowing after assertions: Use Assert::notNull(), Assert::integer(), Assert::isOfAnyType([...]) to guide PHPStan through union-type refinement.

  Assert::integer($value); // PHPStan now treats $value as int below
  

• Array key assertions: Assert::keyExists() and Assert::keyIsset() allow PHPStan to eliminate ?T or nullability in accessing array keys.

  Assert::keyExists($config, 'db');
  $dbConfig = $config['db']; // No null check needed
  

• Combining with @param/@return: Pair assertion contracts with PHPDoc for clarity — the extension reinforces assertions, making PHPDoc a source of truth for runtime behavior.
• Integration with Laravel requests: Use Assert::all() or Assert::keys() on request()->all() after validation to narrow validated shapes for downstream logic.

Gotchas and Tips

• ⚠️ Extension only supports beberlei/assert syntax — does not work with webmozart/assert or ralouphie/multibyte. Don’t expect Assert::startsWith(...) from other libraries to be recognized.
• ⚠️ Assert::true($x) only narrows to bool true, not bool — use Assert::boolean() if you want to accept both true/false.
• 🔧 Custom assertion classes: If you extend Assert, add @phpstan-method annotations or use parameterNameCase workarounds — PHPStan may not resolve narrowed types for subclasses.
• 🐞 Debug tip: Run phpstan --debug and look for Type-specifying extensions to verify the extension is active. If narrowing isn’t happening, ensure beberlei/assert is installed (composer require beberlei/assert).
• 📦 Optional strictness: This extension enhances PHPStan — it doesn’t replace validating/asserting in production. Keep runtime assertions (or use assert() with zend.assertions=1) for production safety.