Parental Laravel Package

Getting Started

1. Install via composer require tightenco/parental (note: tightenco, not tighten in the package name).
2. Add the Parental trait to your parent model (e.g., Document), which must extend Illuminate\Database\Eloquent\Model.
3. Create child models that extend the parent (e.g., Invoice extends Document). No extra traits needed.
4. Ensure the type column exists in the shared table (default column name; configure via $childTypeColumn if needed).
5. First use case: Document::all() automatically hydrates rows as Invoice, Receipt, etc., based on the type column — no manual casting.

✅ Key insight: You don’t instantiate child models directly for persistence; the parent model’s Parental trait intercepts query construction and model resolution automatically.

Implementation Patterns

• Type aliasing: Use $childTypeAliases to store compact DB values ('inv' instead of 'Invoice'), especially when DB values must be stable across refactors.

  class Document extends Model
  {
      use Parental;
      protected $childTypeAliases = ['Invoice' => 'inv', 'Receipt' => 'rcpt'];
  }
  

• Dynamic type switching: Use become(Child::class) to permanently convert a record to another type (updates DB and returns new instance).
• Smart eager loading: Use withChildType('relationship') and hasChildType('relationship') to load/filter only relationships that exist on specific child types.
• Custom type resolution: Override childType() to derive the type from complex conditions (e.g., status-based fallback).
• Enum integration: Leverage PHP enums in the type column with cast(['type' => DocumentType::class]) — ensure enum cases match stored values or aliases.

💡 Pro tip: Define child models empty by default — they inherit all relationships, accessors, and logic from the parent. Only override what differs.

Gotchas and Tips

• Serialization breaks with mixed collections pre-v1.3.4: Always upgrade to ≥ v1.3.6 if using ->toJson() on collections containing multiple child types.
• fillable isn’t auto-merged in old versions: Ensure composer.lock has ≥ v1.3.6; otherwise, fillable arrays don’t combine across inheritance layers.
• Event double-firing in Laravel ≥13: If binding events on the parent class (e.g., Document::created(...)), wrap event registration in whenBooted() (see v1.6.0 changelog).
• Polymorphic relations fail silently if type DB value doesn’t match child class name or alias — debug with Document::classToAlias(Invoice::class).
• Nova compatibility requires alignment: Set childTypeColumn in the parent model and ensure Nova resources reference child models explicitly.
• ::first() vs ::get(): first() returns the first row as its concrete type; get() returns a collection of correct child types. Don’t assume type homogeneity.
• Lumen needs explicit setup: Since v0.9.1, it works standalone — but ensure ParentalServiceProvider is registered manually in bootstrap/app.php.