Php Enum Laravel Package

Getting Started

Install the package with composer require myclabs/php-enum. Start by defining enums as final classes extending MyCLabs\Enum\Enum, using private constants for values (e.g., private const VIEW = 'view';). Use PHPDoc @method annotations for IDE autocomplete (e.g., @method static Action VIEW()), or implement static methods manually if stricter completion is needed. Use the enum as a type hint (function setAction(Action $action)) and instantiate via Action::VIEW() or new Action('view').

Implementation Patterns

• Type-safe domain values: Replace string/int flags (e.g., OrderStatus::PENDING, ShippingMethod::EXPRESS) with typed enums for method signatures and validation.
• Value encapsulation: Add domain-specific logic directly in the enum (e.g., public function label(): string { return match($this->getValue()) { 'pending' => 'Awaiting Payment', ... }; }).
• I/O bridging: Use from($value) to convert request/query parameters into typed enums; rely on isValid() for safe validation before coercion.
• Symfony/Laravel integration: Use alongside ParamConverters (e.g., MyCLabsEnumParamConverter) to auto-resolve enums from route parameters or form data.
• Testing & debugging: Leverage toArray(), values(), and search() to generate fixtures, validate dropdowns, or debug payloads.

Gotchas and Tips

• PHP 8.1+ migration: This library is effectively deprecated for new code—migrate to native enums when possible (changes: Action::VIEW() → Action::VIEW, ->getValue() → ->value, == → ===, keys() → ->name). The package includes an official migration guide.
• IDE autocomplete: Static methods like Action::VIEW() are magically added via __callStatic()—they won’t show in IDEs without @method annotations. Use PhpStorm’s native support or redeclare static methods.
• Inheritance: Enums can be extended (unless final) to add values, but this breaks type safety in tight contracts—prefer composition over inheritance.
• Null handling: Enums strictly enforce non-null values. To support nullables, use ?Action type hints or define null as a valid constant (though not recommended).
• JSON serialization: Implements JsonSerializable out-of-the-box—json_encode($enum) yields the scalar value (e.g., "view"), not an object.
• Version quirks: Pre-1.8.0 had constructor-only instantiation; upgrade to from() for forward compatibility with native enums. Ensure ext-json is installed—missing JSON extension causes runtime failures (fixed in 1.6.6+).
• Psalm/PHPStan: Use @extends Enum<Action::*> and @phpstan-assert annotations (or use PHP 8.2+ native Pure attributes in newer versions) for precise static analysis. Avoid manual @template annotations (renamed in 1.7.6+ to prevent conflicts).