Enum Eloquent Laravel Package

Getting Started

Install the package via composer require konekt/enum-eloquent, ensuring konekt/enum (v2–4) is also present. Define an enum class extending \Konekt\Enum\Enum (e.g., OrderStatus with constants like PENDING, COMPLETED). In your Eloquent model, import and use the CastsEnums trait, then declare attributes to cast in $enums (e.g., 'status' => OrderStatus::class). From there, assign strings or enum instances to the attribute—Laravel will automatically hydrate it into an enum object on retrieval, enabling calls like $order->status->isCompleted().

Implementation Patterns

• Standard Enum Casting: Use $enums to declare state attributes (status, type, tier) for compile-time safety and IDE autocompletion—ideal for domain entities like Orders, Users, or Payments.
• Deferred Enum Resolution: Leverage "Namespace\Resolver@method" syntax (e.g., 'role' => 'RoleResolver@enumClass') for package-level or multi-tenant models, letting consumers override the enum class via config—essential for reusable libraries.
• Form Integration: When using Laravel Collective’s Form, add EnumsAreCompatibleWithLaravelForms alongside CastsEnums to prevent form fields from rendering labels instead of scalar values (e.g., "pending" instead of "Pending Order").
• Bulk Operations & Relations: Works transparently with create(), update(), find(), and relationship assignments—even when mixing scalar strings and enum instances in mass assignment.
• Validation Synergy: Pair with Laravel’s Rule::in(OrderStatus::values()) for explicit validation; the cast ensures invalid values are caught at persistence if validation is skipped (throwing UnexpectedValueException).

Gotchas and Tips

• Invalid Values Kill Requests: Assignment/hydration of unknown DB values (e.g., 'processing' when only 'pending', 'completed' exist) throws UnexpectedValueException. Always seed valid values or wrap hydration in try/catch for migration scenarios.
• No DB-Enum Dependency: Store enum columns as VARCHAR—avoid MySQL ENUM type for portability and easier schema changes. This package operates at the PHP layer, independent of DB-level enum constraints.
• __DEFAULT ≠ Database Default: The enum’s __DEFAULT constant only affects PHP-side fallback (e.g., null → default enum instance). For persistence, set column default in migrations if needed.
• Resolver Gotchas: Runtime resolvers (Class@method) require a static method returning a valid enum class. Misconfiguration causes cryptic Constant ... not found errors—test resolver output in tests or tinker.
• Form Helpers Require Dual Trait: Omitting EnumsAreCompatibleWithLaravelForms causes forms to use the enum’s label (e.g., "Pending") instead of the stored value ("pending"), breaking updates—add it explicitly when using Collective.
• Debugging Tools: Use dd($enum->values()) to inspect all valid values, get_class($model->attr) to verify enum resolution, and enum::options() (if using konekt/enum’s helpers) for labels—especially handy when runtime resolvers are involved.