Single Table Inheritance Laravel Package

Getting Started

• Requires PHP 8.1+ (v1.1.0 raises the minimum from previous versions). Confirm your app and CI images meet this before upgrading. Laravel 8/9/10 are supported depending on the package's composer constraints.
• Install with composer require <vendor>/<package> (or upgrade to ^1.1). If you are on PHP 8.0 or lower, stay on the previous minor until you upgrade PHP.
• Look first at the package's enum casting and validation docs. v1.1.0 adds first-class support for native PHP 8.1 enum types, so the quickest win is replacing string constants or custom enum classes with backed enums.
• First use case: define a backed enum for a model status, cast it on the Eloquent model, and validate it in a form request:

enum Status: string {
    case Draft = 'draft';
    case Published = 'published';
}

class Post extends Model {
    protected $casts = ['status' => Status::class];
}

// Form request
'status' => ['required', Rule::enum(Status::class)],

Implementation Patterns

• Eloquent casts: Use backed enums (string or int) directly in $casts. The package resolves the enum instance on attribute access and stores the backing value on save.
• Validation: Prefer Laravel's Rule::enum(Status::class) where available; the package may provide its own rule or polyfill for older Laravel versions. Use tryFrom() for untrusted input and from() only for known-valid values.
• Form requests and controllers: Type-hint enum cases in method signatures where the package supports route binding, or resolve with Status::from($request->validated('status')).
• API resources: Serialize explicitly—$this->status->value for storage/API payloads and $this->status->name for human-readable labels. Avoid relying on implicit __toString() unless the package documents it.
• Query scopes and filters: Compare against enum cases directly: Post::where('status', Status::Published)->get(). For select inputs, use Status::cases() to build options.
• Factories and seeders: Use enum cases (Status::Draft) rather than raw strings to keep test data aligned with production types.
• Migration path: If you previously used the package's custom enum classes, migrate incrementally. Native enums are not drop-in replacements for class-based enums—update casts, validation rules, and any label()/description() helpers to use interfaces or traits.
• Blade and UI: Compare with === against enum cases; use ->value when emitting data attributes or hidden inputs.

Gotchas and Tips

• Breaking PHP requirement: v1.1.0 will not install on PHP 8.0 or lower. Update composer.json platform config and CI matrices before upgrading. Run composer why-not <package> 1.1 if the upgrade is blocked.
• Backed enums only for casts: Pure (non-backed) enums cannot be persisted to the database. Use string or int backing types.
• Enums are final: Native enums cannot be extended. Put shared behavior in traits or interfaces rather than trying to subclass.
• Nullable columns: Use ?Status::class casts and handle null explicitly; tryFrom() returns null on failure, which is useful for optional filters.
• Serialization consistency: Decide early whether your API exposes ->value or ->name. Mixing them causes subtle frontend bugs. Add a toArray() override or API resource mapping if needed.
• Validation rule availability: Rule::enum() is available in newer Laravel versions; if you are on an older minor, use the package's rule or in:. Confirm the package's compatibility matrix.
• Testing: Assert against enum instances (assertSame(Status::Draft, $post->status)) rather than strings. This catches cast regressions early.
• Debugging upgrades: Clear config and cache after upgrading (php artisan config:clear, composer dump-autoload). If casts fail, check that the enum is backed and the column type matches the backing type.
• Extension points: Publish the package config if available to customize label/description resolution. Use interfaces (e.g., HasLabel) on enums to keep presentation logic out of models.