Php Enum Phpstan Laravel Package

Getting Started

1. Install via Composer in your Laravel project:

   composer require --dev marc-mabe/php-enum-phpstan
   

2. Include the extension in your PHPStan config (phpstan.neon or phpstan.dist.neon):

   includes:
     - vendor/marc-mabe/php-enum-phpstan/extension.neon
   

3. Start using it today by defining a php-enum enum (e.g., StringEnum or IntEnum) and writing code like MyEnum::STATUS_ACTIVE->getValue(). PHPStan will now correctly infer the return type (string/int) and detect invalid accesses (e.g., MyEnum::NON_EXISTENT) before running tests or production.

Implementation Patterns

• Type-safe enum construction: Use MyEnum::from($input) with full confidence—PHPStan knows it returns MyEnum|null (or MyEnum if strict-null checks are off), and errors on invalid scalar types.
• Autocomplete & refactoring safety: IDEs and PHPStan now recognize MyEnum::ACTIVE, MyEnum::getValues(), MyEnum::getValuesAsArray(), etc., enabling reliable refactor-safe method calls.
• Union enum analysis: When using MyUnionEnum extends IntEnum|StringEnum, PHPStan infers correct union return types from getValues() → array<int|string>—critical for payload parsing in APIs.
• Deprecation tracking: Annotate enum constants with @deprecated (e.g., in MyEnum::OLD_STATUS), and PHPStan will emit warnings when used, aiding deprecation workflows.
• CI-ready analysis: Add vendor/bin/phpstan analyse --memory-limit=2G to your pipeline to catch enum misuse early—especially valuable when evolving APIs or consolidating enum usage.

Gotchas and Tips

• Strict dependency chain: Ensure both marc-mabe/php-enum (≥4.0) and phpstan/phpstan (≥2.0) are installed. Mismatched versions silently disable inference. Run composer why marc-mabe/php-enum and composer show phpstan/phpstan to verify.
• Static calls on variables may misbehave: While v3 fixes many cases ($enumClass::getValues()), deeply dynamic constructs like call_user_func([$className, 'getValues']) won’t be resolved—fall back to @phpstan-var or @phpstan-ignore.
• No IDE autocomplete by default: PHPStan improves static analysis, not editor hints. For PhpStorm/VSCode enum method autocompletion, pair with phpstan/phpstan-deprecation-rules or consider adding stubs via stubFiles.
• Custom enum methods ignored: Only built-in php-enum methods are handled. For custom logic (e.g., MyEnum::isDefault()), either:
  • Add @return in docblocks, or
  • Write a custom PHPStan rule using php-enum’s reflection API.
• CI performance tip: Skip analysis of tests/ and database/ folders (you rarely need enum checks there) via ignoreErrors or skipAnalyze in config.