Getting Started

Install with Composer and confirm the package version resolves to ^3.0. v3.0.4 is a patch release that adds Laravel 13 support and PHPStan 1.x support; no application migration is expected from 3.0.3.
Start with the package README’s enum-definition and Eloquent-cast examples. The fastest first use case is replacing a string status/type column with a backed enum and casting it on the model.
Minimal path: define the enum, register the cast, replace string comparisons in the model/domain code with enum cases, then add request validation and API serialization around the same enum.
Run the existing test suite after upgrading. If you use PHPStan, ensure the package’s PHPStan extension/support is wired into your analysis config.

Implementation Patterns

Use enums as the single source of truth for allowed values, labels, and transitions; keep database values backed by the enum’s value, not its label.
Model casts are the main integration point: cast attributes to the enum, then use enum methods in scopes, policies, state machines, and service classes instead of raw strings.
Validation should normalize input to the enum’s backed value before persistence. Use the package’s validation integration where provided, or Laravel’s native enum rule when only native checks are needed.
Query scopes and filters should accept enum cases or backed values and convert explicitly. This keeps controllers and form requests from leaking raw strings into queries.
API resources should map enums deliberately: expose the backed value for clients and a separate label/description only if the frontend needs it.
Factories and seeders should use enum cases rather than hard-coded strings so fixture data stays aligned with the enum contract.
For static analysis, enable PHPStan 1.x support and add enum-specific types/rules to CI. This is especially useful when enums are used across casts, validation, and query scopes.
Keep presentation concerns such as translated labels in a separate presenter/resource when enums are reused across multiple contexts.

v3.0.4 is a maintenance release: Laravel 13 support, PHPStan 1.x support, a token-boundary fix, and internal tooling/docs changes. Treat it as a safe patch upgrade, but still run your full test matrix.
The backed values are a database contract. Renaming a case is safe only if its backed value stays the same; changing the backed value requires a data migration.
Invalid database values will fail enum casting. Clean up legacy data or use tryFrom-style handling before rolling out casts to existing tables.
Avoid mixing native Laravel enum casting and package-specific casting behavior in the same model unless the package documents that combination.
The token-boundary fix matters if you rely on enum token/name resolution or static analysis. Add a regression test for enum cases with shared prefixes or similar names.
Do not store labels in the database. Store backed values and derive labels at the presentation layer.
Clear Laravel config/cache after changing enum-related configuration or casts, and verify Composer constraints if Laravel 13 or PHPStan 1.x support does not appear after update.
Extension points to watch: custom labels/descriptions, query scopes, validation rules, and PHPStan configuration. Keep these thin so enum classes remain portable domain objects.