Single Table Inheritance for Eloquent Models Using Parental

Parental is a Laravel package by Tighten that brings Single Table Inheritance (STI) to Eloquent. Instead of creating separate database tables for each model variation, Parental lets you extend a parent model with child classes that all share the same table, with a type column distinguishing between them.

Use Cases

Single Table Inheritance is useful when you have models that share most of the same attributes but differ in behavior. Common examples include:

User types - An Admin and a Guest that extend a base User model, each with their own methods and relationships
Content types - A TextPost and ImagePost that extend a Post model, with type-specific relationships like mentions or attachments
Order states - A PendingOrder and ShippedOrder that extend an Order, where state transitions change the model type

Getting Started

Install the package via Composer:

composer require tightenco/parental

Next, define your parent and child models by adding the HasChildren trait to the parent model and the HasParent trait to each child model. Each child class extends the parent and reads from and writes to the same database table:

use Illuminate\Database\Eloquent\Model;
use Tighten\Parental\HasChildren;
 
class Order extends Model
{
    use HasChildren;
}

use Tighten\Parental\HasParent;
 
class PendingOrder extends Order
{
    use HasParent;
}

use Tighten\Parental\HasParent;
 
class ShippedOrder extends Order
{
    use HasParent;
}

When you create a PendingOrder or ShippedOrder, the record is stored in the orders table with a type column set to identify the child class.

Custom Type Column

If your table uses a column name other than type, override it with the $childColumn property on the parent model:

class Order extends Model
{
    use HasChildren;
 
    protected $childColumn = 'status';
}

Custom Type Aliases

By default, Parental stores the fully-qualified class name in the type column. You can map shorter aliases using the $childTypes property on the parent model:

use Illuminate\Database\Eloquent\Model;
use Tighten\Parental\HasChildren;
 
class Order extends Model
{
    use HasChildren;
 
    protected $childTypes = [
        'pending' => PendingOrder::class,
        'shipped' => ShippedOrder::class,
    ];
}

This stores pending or shipped in the database instead of the full class name. The type column also supports integer values if you prefer numeric identifiers:

protected $childTypes = [
    1 => PendingOrder::class,
    2 => ShippedOrder::class,
];

Transitioning Between Types with `become()`

The become() method lets you switch a model from one child type to another at runtime. For example, when an order moves through its lifecycle, you can re-cast it to a different class:

$order = PendingOrder::findOrFail(1);
 
$order = $order->become(ShippedOrder::class);
$order->save();

The call returns a fresh instance of the target class with all the original attributes carried over. Parental also dispatches a becoming event before the switch, so you can listen for type changes and run additional logic when they happen.

Eager Loading Child-Specific Relationships

When a query returns a mix of child types, you may need to load relationships that only exist on certain classes. Calling a standard load() with a relationship defined on just one child type would throw an error. Parental ships with dedicated helpers that handle this by scoping the eager load to the correct child class:

$orders->loadChildren([
    PendingOrder::class => ['items'],
    ShippedOrder::class => ['shipments'],
]);

These helpers work on Eloquent query builders, collections, and paginators:

// On queries
Order::childrenWith([
    PendingOrder::class => ['items'],
    ShippedOrder::class => ['shipments'],
])->get();
 
// Count child-specific relationships
Order::childrenWithCount([
    PendingOrder::class => ['items'],
    ShippedOrder::class => ['shipments'],
])->get();