Eloquent Role Inheritance Extension

This extension provides support for Eloquent relation role (table inheritance) composition.

For license information check the LICENSE-file.

Installation

The preferred way to install this extension is through composer.

Either run

or add

to the require section of your composer.json.

Usage

This extension provides support for Eloquent relation role composition, which is also known as table inheritance.

For example: assume we have a database for the University. There are students studying in the University, and there are instructors teaching the students. Student has a study group and scholarship information, while instructor has a rank and salary. However, both student and instructor have name, address, phone number and so on. Thus we can split their data in the three different tables:

• 'humans' - stores common data
• 'students' - stores student special data and reference to the 'humans' record
• 'instructors' - stores instructor special data and reference to the 'humans' record

DDL for such solution may look like following:

This extension introduces \Illuminatech\DbRole\InheritRole trait, which allows role relation based Eloquent inheritance. In order to make it work, first of all, you should create an Eloquent class for the base table, in our example it will be 'humans':

Then you will be able to compose Eloquent classes, which implements role-based inheritance using \Illuminatech\DbRole\InheritRole. There are 2 different ways for such classes composition:

• Master role inheritance
• Slave role inheritance

Master role inheritance

This approach assumes role Eloquent class to be a descendant of the base role class, using 'has-one' relation to the slave one.

The main benefit of this approach is that role class directly inherits all methods and logic from the base one. However, you'll need to declare an extra Eloquent class, which corresponds the role table. In order separate 'Student' records from 'Instructor' ones during the search process, a default scope named 'inherit-role' automatically defined, adding roleMarkingAttributes() to the query 'where' condition.

This approach should be chosen in case most functionality depends on the 'Human' attributes.

Slave role inheritance

This approach assumes a role Eloquent class does not extends the base one, but relates to it via 'belongs-to':

This approach does not require extra Eloquent class for functioning, and it does not need default scope specification. It does not directly inherit logic declared in the base Eloquent model, however any custom method declared in the related class will be available via magic method __call() mechanism. Thus, if class Human has method sayHello(), you are able to invoke it through Instructor instance.

This approach should be chosen in case most functionality depends on the 'Instructor' attributes.

Accessing role attributes

After being attached, \Illuminatech\DbRole\InheritRole provides access to the properties of the model bound by relation, which is specified via \Illuminatech\DbRole\InheritRole::roleRelationName(), as they were the main one:

However, this will work only for the attributes, which have been explicitly defined at related model via \Illuminate\Database\Eloquent\Model::$fillable or \Illuminate\Database\Eloquent\Model::$guarded. Thus in order to make example from above function, classes used for the relations should be defined in following way:

If the related model does not exist, for example, in case of new record, it will be automatically instantiated on the first attempt to set role attribute:

Accessing role methods

Any non-static method declared in the model related via \Illuminatech\DbRole\InheritRole::roleRelationName() can be accessed from the owner model:

This feature allows to inherit logic from the base role model in case of using 'slave' approach. However, this works both for the 'master' and 'slave' role approaches.

Saving role data

When main model is saved the related role model will be saved as well:

When main model is deleted related role model will be deleted as well:

Querying role records

\Illuminatech\DbRole\InheritRole works through relations. Thus, in order to make role attributes feature work, it will perform an extra query to retrieve the role slave or master model, which may produce performance impact in case you are working with several models. In order to reduce number of queries you may use with() on the role relation:

You may apply 'with' for the role relation as default scope for the Eloquent query:

Tip: you may name slave table primary key same as master one: use 'id' instead of 'human_id' for it. In this case conditions based on primary key will be always the same. However, this trick may cause extra troubles in case you are using joins for role relations at some point.

If you need to specify search condition based on fields from both entities and you are using relational database, you can use join() method.

Creating role setup web interface

Figuratively speaking, \Illuminatech\DbRole\InheritRole merges 2 Eloquent classes into a single one. This means you don't need anything special, while creating web interface for their editing. However, you should remember to add role attributes to the \Illuminate\Database\Eloquent\Model::$fillable list in order to make them available for mass assignment.

Then controller, which performs the data storage may look like following: