What is Single Table Inheritance?

I saw a post by Kapil Verma where he shared his STI base class. I cleaned it up a bit and it seems to be running solidly. There may be omissions. But, I'll update it as I use it.

abstract class SingleTableInheritanceEntity extends Eloquent
{
    // the field that stores the subclass
    protected $subclassField = null;
    // must be overridden and set to true in subclasses
    protected $isSubclass = false;

    public function isSubclass()
    {
        return $this->isSubclass;
    }

    // if no subclass is defined, function as normal
    public function mapData(array $attributes)
    {
        if ( ! $this->subclassField) {
            return $this->newInstance();
        }

        return new $attributes[$this->subclassField];
    }

    // instead of using $this->newInstance(), call
    // newInstance() on the object from mapData
    public function newFromBuilder($attributes = array())
    {
        $instance = $this->mapData((array) $attributes)->newInstance(array(), true);
        $instance->setRawAttributes((array) $attributes, true);
        return $instance;
    }

    public function newQuery($excludeDeleted = true)
    {
        // If using Laravel 4.0.x then use the following commented version of this command
        // $builder = new Builder($this->newBaseQueryBuilder());
        // newEloquentBuilder() was added in 4.1
        $builder = $this->newEloquentBuilder($this->newBaseQueryBuilder());

        // Once we have the query builders, we will set the model instances so the
        // builder can easily access any information it may need from the model
        // while it is constructing and executing various queries against it.
        $builder->setModel($this)->with($this->with);

        if ($excludeDeleted && $this->softDelete) {
            $builder->whereNull($this->getQualifiedDeletedAtColumn());
        }

        if ($this->subclassField && $this->isSubclass()) {
            $builder->where($this->subclassField, '=', get_class($this));
        }

        return $builder;
    }

    // ensure that the subclass field is assigned on save
    public function save(array $options = array())
    {
        if ($this->subclassField) {
            $this->attributes[$this->subclassField] = get_class($this);
        }
        return parent::save($options);
    }
}

Then, let's imagine that you have a notifications database table. It has a few fields, id, user_id, class, subject_type, subject_id. Subject is a polymorphic relation to the item that the notification is for. Then, we have a class ForumTag so that if a user is tagged no the forum, it creates this sort of notification.

class Notification extends SingleTableInheritanceEntity
{
    protected $table = 'notifications';
    protected $subclassField = 'class';

    public function setSubject(Model $object)
    {
        $this->attributes['subject_type'] = get_class($object);
        $this->attributes['subject_id'] = $object->getKey();
    }
}

class ForumTag extends Notification
{
    protected $isSubclass = true;
}

creating a notification

$notification = new ForumTag;
$notification->setSubject($forumThread);
$notification->save();

retrieve all of a user's notifications

The resulting collection here will include ForumTag classes.

$notifications = Notification::where('user_id', '=', $userId)->get();

retrieve specifically only ForumTag notificatinos

$notifications = ForumTag::where('user_id', '=', $userId)->get();

Warning

Single Table Inheritance should only be used when different types have the exact same fields, but need different behavior. You never want to end up adding new nullable fields just for the needs of a specific type.

More Information on When and Why to use Single Table Inheritance