wfeller/parental

A simple eloquent trait that allows relationships to be accessed through child models.

0.16.0 2026-05-24 13:27 UTC

Requires

• php: ^8.3
• illuminate/database: ^11.0|^12.0|^13.0

Requires (Dev)

• orchestra/testbench: ^9.0|^10.0|^11.0
• phpunit/phpunit: ^10.0|^11.0|^12.0

MIT

• Caleb Porzio
• William

README

Parental is a Laravel package, forked from calebporzio/parental, that brings STI (Single Table Inheritance) capabilities to Eloquent.

What is single table inheritance (STI)?

It's a fancy name for a simple concept: Extending a model (usually to add specific behavior), but referencing the same table.

Licence

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you'll be creating employment for local families and restoring wildlife habitats.

You can buy trees here offset.earth/treeware

Read more about Treeware at treeware.earth

Installation

composer require "wfeller/parental"

Simple Usage

// The "parent"
class User extends Model
{
    //
}

// The "child"
class Admin extends User
{
    use \WF\Parental\HasParent;

    public function impersonate($user) {
        ...
    }
}

// Returns "Admin" model, but reference "users" table:
$admin = Admin::first();

// Can now access behavior exclusive to "Admin"s
$admin->impersonate($user);

What problem did we just solve?

Without Parental, calling Admin::first() would throw an error because Laravel would be looking for an admins table. Laravel generates expected table names, as well as foreign keys and pivot table names, using the model's class name. By adding the HasParent trait to the Admin model, Laravel will now reference the parent model's class name users.

Accessing Child Models from Parents

// First, we need to create a `type` column on the `users` table
Schema::table('users', function ($table) {
    $table->string('type')->nullable();
});

// The "parent"
class User extends Model
{
    use WF\Parental\HasChildren;

    protected $fillable = ['type'];
}

// A "child"
class Admin extends User
{
    use \WF\Parental\HasParent;
}

// Another "child"
class Guest extends User
{
    use \WF\Parental\HasParent;
}

// Adds row to "users" table with "type" column set to: "App/Admin"
Admin::create(...);

// Adds row to "users" table with "type" column set to: "App/Guest"
Guest::create(...);

// Returns 2 model instances: Admin, and Guest
User::all();

What problem did we just solve?

Before, if we ran: User::first() we would only get back User models. By adding the HasChildren trait and a type column to the users table, running User::first() will return an instance of the child model (Admin or Guest in this case).

Type Aliases

If you don't want to store raw class names in the type column, you can override them using the $childTypes property.

class User extends Model
{
    use \WF\Parental\HasChildren;

    protected $fillable = ['type'];

    protected $childTypes = [
        'admin' => App\Admin::class,
        'guest' => App\Guest::class,
    ];
}

Now, running Admin::create() will set the type column in the users table to admin instead of App\Admin.

This feature is useful if you are working with an existing type column, or if you want to decouple application details from your database.

Custom Type Column Name

You can override the default type column by setting the $childColumn property on the parent model.

class User extends Model
{
    use \WF\Parental\HasChildren;

    protected $fillable = ['parental_type'];

    protected $childColumn = 'parental_type';
}

Parent Type / Default Type Alias

You can optionally set a default type value for parent model instances using the $parentType property. This is useful when your parent rows should have a specific type identifier rather than NULL.

class User extends Model
{
    use \WF\Parental\HasChildren;

    protected $parentType = 'user';
}

Now when you create a plain User instance, the type column will be set to user instead of NULL.

Handling Unknown Type Values

By default, if a row in your database has an unknown type value (one that doesn't match any class in $childTypes), Parental will throw a Class not found error when hydrating the model.

If you want unknown type values to gracefully fall back to the parent class instead of throwing an error, implement the DefaultsMissingAliasToParentClass interface on your parent model:

use WF\Parental\DefaultsMissingAliasToParentClass;
use WF\Parental\HasChildren;

class Vehicle extends Model implements DefaultsMissingAliasToParentClass
{
    use HasChildren;

    protected $childTypes = [
        'car' => Car::class,
    ];
}

With this interface, any type value that isn't "car" will instantiate a plain Vehicle instead of throwing an error. This is especially useful when:

• Working with legacy databases that contain stale or inconsistent type values
• Rolling out STI gradually across existing data
• You need defensive behaviour in production where bad data should never crash a page load