PHPackages                             carsdotcom/single-table-inheritance - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. carsdotcom/single-table-inheritance

ActiveLibrary[Database & ORM](/categories/database)

carsdotcom/single-table-inheritance
===================================

Single Table Inheritance Trait

1.0.1(2y ago)011.4k↓12.8%MITPHPPHP >= 8.0

Since Jul 2Pushed 2y agoCompare

[ Source](https://github.com/carsdotcom/single-table-inheritance)[ Packagist](https://packagist.org/packages/carsdotcom/single-table-inheritance)[ RSS](/packages/carsdotcom-single-table-inheritance/feed)WikiDiscussions main Synced yesterday

READMEChangelog (1)Dependencies (5)Versions (2)Used By (0)

Single Table Inheritance
========================

[](#single-table-inheritance)

[![Build Status](https://github.com/bostanio/single-table-inheritance/workflows/Unit%20Tests/badge.svg)](https://github.com/bostanio/single-table-inheritance/actions)[![Latest Stable Version](https://camo.githubusercontent.com/6abeb8ef03bf29ac7968a0a71944b87dc0327c92d6697dec55d7f9c559e8b7fb/68747470733a2f2f706f7365722e707567782e6f72672f6e616e6967616e732f73696e676c652d7461626c652d696e6865726974616e63652f762f737461626c652e737667)](https://packagist.org/packages/nanigans/single-table-inheritance)[![Total Downloads](https://camo.githubusercontent.com/c2876cb938d307e1de6e25814e1949ce46bba4bfb4336069d8926538946acf83/68747470733a2f2f706f7365722e707567782e6f72672f6e616e6967616e732f73696e676c652d7461626c652d696e6865726974616e63652f646f776e6c6f6164732e737667)](https://packagist.org/packages/nanigans/single-table-inheritance)[![Latest Unstable Version](https://camo.githubusercontent.com/271814c3a9cc92e5522aba795b521428852ca085246e8fc440ea07e4c6b92df9/68747470733a2f2f706f7365722e707567782e6f72672f6e616e6967616e732f73696e676c652d7461626c652d696e6865726974616e63652f762f756e737461626c652e737667)](https://packagist.org/packages/nanigans/single-table-inheritance)[![License](https://camo.githubusercontent.com/3e4bfb8147396fbd765d32edf6647da636a5335bcfcf05dfca18a1f263560d51/68747470733a2f2f706f7365722e707567782e6f72672f6e616e6967616e732f73696e676c652d7461626c652d696e6865726974616e63652f6c6963656e73652e737667)](https://packagist.org/packages/nanigans/single-table-inheritance)

Single Table Inheritance is a trait for Laravel 9+ Eloquent models that allows multiple models to be stored in the same database table. We support a few key features

- Implemented as a Trait so that it plays nice with others, such as Laravel's `SoftDeletingTrait` or the excellent [Validating](https://github.com/dwightwatson/validating), without requiring a complicated mess of Eloquent Model subclasses.
- Allow arbitrary class hierarchies not just two-level parent-child relationships.
- Customizable database column name that is used to store the model type.
- Customizable string for the model type value stored in the database. (As opposed to forcing the use of the fully qualified model class name.)
- Allow database rows that don't map to known model types. They will never be returned in queries.

Installation
============

[](#installation)

Simply add the package to your `composer.json` file and run `composer update`.

```
"carsdotcom/single-table-inheritance": "^1.0.1"

```

Or go to your project directory where the `composer.json` file is located and type:

```
composer require "carsdotcom/single-table-inheritance:^1.0.1"
```

For Laravel before 9.x you can still use [jonspalmer/single-table-inheritance:1.0.0](https://github.com/jonspalmer/single-table-inheritance)

Overview
========

[](#overview)

Getting started with the Single Table Inheritance Trait is simple. Add the constraint and add a few properties to your models. A complete example of a `Vehicle` super class with two subclasses `Truck` and `Car` is given by

```
use Nanigans\SingleTableInheritance\SingleTableInheritanceTrait;

class Vehicle extends Model
{
  use SingleTableInheritanceTrait;

  protected $table = "vehicles";

  protected static $singleTableTypeField = 'type';

  protected static $singleTableSubclasses = [Car::class, Truck::class];
}

class Car extends Vehicle
{
  protected static $singleTableType = 'car';
}

class Truck extends Vehicle
{
  protected static $singleTableType = 'truck';
}
```

There are four required properties to be defined in your classes:

### Define the database table

[](#define-the-database-table)

In the root model set the `protected` property `$table` to define which database table to use to store all your classes.
*Note:* even if you are using the default for the root class (i.e. the 'vehicles' table for the `Vehicle` class) this is required so that subclasses inherit the same setting rather than defaulting to their own table name.

### Define the database column to store the class type

[](#define-the-database-column-to-store-the-class-type)

In the root model set the `protected static` property `$singleTableTypeField` to define which database column to use to store the type of each class.

### Define the subclasses

[](#define-the-subclasses)

In the root model and each branch model define the `protected static` property `$singleTableSubclasses` to define which subclasses are part of the classes hierarchy.

### Define the values for class type

[](#define-the-values-for-class-type)

In each concrete class set the `protected static` property `$singleTableType` to define the string value for this class that will be stored in the `$singleTableTypeField` database column.

Multi Level Class Hierarchies
-----------------------------

[](#multi-level-class-hierarchies)

It's not uncommon to have many levels in your class hierarchy. Its easy to define that structure by declaring subclasses at each level. For example suppose you have a Vehicle super class with two subclasses Bike and MotorVehicle. MotorVehicle in trun has two subclasses Car and Truck. You would define the classes like this:

```
use Nanigans\SingleTableInheritance\SingleTableInheritanceTrait;

class Vehicle extends Model
{
  use SingleTableInheritanceTrait;

  protected $table = "vehicles";

  protected static $singleTableTypeField = 'type';

  protected static $singleTableSubclasses = [MotorVehicle::class, Bike::class];
}

class MotorVehicle extends Vehicle
{
  protected static $singleTableSubclasses = [Car::class, Truck::class];
}

class Car extends MotorVehicle
{
  protected static $singleTableType = 'car';
}

class Truck extends MotorVehicle
{
  protected static $singleTableType = 'truck';
}

class Bike extends Vehicle
{
  protected static $singleTableType = 'bike';
}
```

Defining Which Attributes Are Persisted
---------------------------------------

[](#defining-which-attributes-are-persisted)

Eloquent is extremely lenient in allowing you to get and set attributes. There is no mechanism to declare the set of attributes that a model supports. If you misuse and attribute it typically results in a SQL error if you try to issue an insert or update for a column that doesn't exist. By default the SingleTableInheritanceTrait operates the same way. However, when storing a class hierarchy in a single table there are often database columns that don't apply to all classes in the hierarchy. That Eloquent will store values in those columns makes it considerably easier to write bugs. There, the SingleTableInheritanceTrait allows you to define which attributes are persisted. The set of persisted attributes is also inherited from parent classes.

```
class Vehicle extends Model
{
  protected static $persisted = ['color']
}

class MotorVehicle extends Vehicle
{
  protected static $persisted = ['fuel']
}
```

In the above example the class `Vehicle` would persist the attribute `color` and the class `MotorVehicle` would persist both `color` and `fuel`.

### Automatically Persisted Attributes

[](#automatically-persisted-attributes)

For convenience the model primary key and any dates are automatically added to the list of persisted attributes.

### BelongsTo Relations

[](#belongsto-relations)

If you are restricting the persisted attribute and your model has BelongsTo relations then you must include the foreign key column of the BelongsTo relation. For example:

```
class Vehicle extends Model
{
  protected static $persisted = ['color', 'owner_id'];

  public function owner()
  {
    return $this->belongsTo('User', 'owner_id');
  }
}
```

Unfortunately there is no efficient way to automatically detect BelongsTo foreign keys.

### Throwing Exceptions for Invalid Attributes

[](#throwing-exceptions-for-invalid-attributes)

By default, the SingleTableInheritanceTrait will handle invalid attributes silently It ignores non-persisted attributes when a model is saved and ignores non-persisted columns when hydrating a model from a builder query. However, you can force exceptions to be thrown when invalid attributes are encountered in either situation by setting the `$throwInvalidAttributeExceptions` property to true.

```
/**
 * Whether the model should throw an InvalidAttributesException if non-persisted
 * attributes are encountered when saving or hydrating a model.
 * If not set, it will default to false.
 *
 * @var boolean
 */
protected static $throwInvalidAttributeExceptions = true;
```

Inspiration
===========

[](#inspiration)

We've chosen a very particular implementation to support single table inheritance. However, others have written code and articles around a general approach that proved influential.

First, Mark Smith has an excellent article (no long live but available in web archive) [Single Table Inheritance in Laravel 4](https://web.archive.org/web/20171224233536/http://www.colorfultyping.com/single-table-inheritance-in-laravel-4/) amongst other things it introduces the importance of queries returning objects of the correct type. Second, Jacopo Beschi wrote and extension of Eloquent's `Model`, [Laravel-Single-Table-Inheritance](https://github.com/intrip/laravel-single-table-inheritance)`, that introduces the importance of being able to define which attributes each model persists.

The use of Traits was heavy influence by the Eloquent's `SoftDeletingTrait` and the excellent [Validating Trait](https://github.com/dwightwatson/validating).

###  Health Score

29

—

LowBetter than 57% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity25

Limited adoption so far

Community17

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor2

2 contributors hold 50%+ of commits

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

731d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/a20e6e10ced1433e8f6c8a137c3abd3897ed284d1c0e397ad656894b93ae9d47?d=identicon)[jwadhams](/maintainers/jwadhams)

![](https://www.gravatar.com/avatar/9c6c9dd822416d8cec97ed1b44d5f943aeb39b1adf2980cb819fc111c5cfaa61?d=identicon)[bbene](/maintainers/bbene)

---

Top Contributors

[![jonspalmer](https://avatars.githubusercontent.com/u/328224?v=4)](https://github.com/jonspalmer "jonspalmer (22 commits)")[![jwadhams](https://avatars.githubusercontent.com/u/1613739?v=4)](https://github.com/jwadhams "jwadhams (10 commits)")[![boris-glumpler](https://avatars.githubusercontent.com/u/580004?v=4)](https://github.com/boris-glumpler "boris-glumpler (2 commits)")[![DenzoNL](https://avatars.githubusercontent.com/u/7504556?v=4)](https://github.com/DenzoNL "DenzoNL (2 commits)")[![gvidal](https://avatars.githubusercontent.com/u/820199?v=4)](https://github.com/gvidal "gvidal (1 commits)")[![isaackearl](https://avatars.githubusercontent.com/u/9354830?v=4)](https://github.com/isaackearl "isaackearl (1 commits)")[![manandhar](https://avatars.githubusercontent.com/u/7371027?v=4)](https://github.com/manandhar "manandhar (1 commits)")[![martdegraaf](https://avatars.githubusercontent.com/u/9855233?v=4)](https://github.com/martdegraaf "martdegraaf (1 commits)")[![reiz](https://avatars.githubusercontent.com/u/652130?v=4)](https://github.com/reiz "reiz (1 commits)")[![bbene](https://avatars.githubusercontent.com/u/502853?v=4)](https://github.com/bbene "bbene (1 commits)")[![thomasschiet](https://avatars.githubusercontent.com/u/286026?v=4)](https://github.com/thomasschiet "thomasschiet (1 commits)")[![bryanashley](https://avatars.githubusercontent.com/u/1095642?v=4)](https://github.com/bryanashley "bryanashley (1 commits)")[![cfothergill](https://avatars.githubusercontent.com/u/542745?v=4)](https://github.com/cfothergill "cfothergill (1 commits)")[![darron1217](https://avatars.githubusercontent.com/u/8064923?v=4)](https://github.com/darron1217 "darron1217 (1 commits)")

---

Tags

laravelmodeleloquenttablesingleinheritance

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/carsdotcom-single-table-inheritance/health.svg)

```
[![Health](https://phpackages.com/badges/carsdotcom-single-table-inheritance/health.svg)](https://phpackages.com/packages/carsdotcom-single-table-inheritance)
```

###  Alternatives

[mongodb/laravel-mongodb

A MongoDB based Eloquent model and Query builder for Laravel

7.1k8.4M96](/packages/mongodb-laravel-mongodb)[kirschbaum-development/eloquent-power-joins

The Laravel magic applied to joins.

1.6k32.6M46](/packages/kirschbaum-development-eloquent-power-joins)[nanigans/single-table-inheritance

Single Table Inheritance Trait

2512.6M3](/packages/nanigans-single-table-inheritance)[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[yajra/laravel-oci8

Oracle DB driver for Laravel via OCI8

8793.2M25](/packages/yajra-laravel-oci8)[spiritix/lada-cache

A Redis based, automated and scalable database caching layer for Laravel

592456.3k2](/packages/spiritix-lada-cache)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)