Add ORM relationship

Author: yidas

README.md

@@ -16,7 +16,7 @@ This ORM Model extension is collected into [yidas/codeigniter-pack](https://gith
 FEATURES
 --------
 
-- ***ORM** Model with **Elegant patterns** as Laravel Eloquent ORM & Yii2 Active Record*
+- ***[ORM](#active-record-orm)** Model with **Elegant patterns** as Laravel Eloquent ORM & Yii2 Active Record*
 
 - ***[CodeIgniter Query Builder](#find)** integration*
 
@@ -58,12 +58,15 @@ OUTLINE
   - [Updates](#updates)
   - [Deletes](#deletes)
   - [Accessing Data](#accessing-data)
+  - [Relationships](#relationships)
   - [Methods](#methods-1)
     - [findone()](#findone)
     - [findAll()](#findall)
     - [save()](#save)
     - [beforeSave()](#beforesave)
     - [afterSave()](#afterave)
+    - [hasOne()](#hasone)
+    - [hasMany()](#hasmany)
     - [toArray()](#toarray)
 - [Soft Deleted](#soft-deleted)
   - [Configuration](#configuration-1)
@@ -638,6 +641,43 @@ $title = $post->title;
 $subtitle = $post['subtitle'];
 ```
 
+### Relationships
+
+Database tables are often related to one another. For example, a blog post may have many comments, or an order could be related to the user who placed it. This library makes managing and working with these relationships easy, and supports different types of relationships:
+
+- [One To One](#hasone)
+- [One To Many](#hasmany)
+
+To work with relational data using Active Record, you first need to declare relations in models. The task is as simple as declaring a `relation method` for every interested relation, like the following,
+
+```php
+class CustomersModel extends yidas\Model
+{
+    // ...
+
+    public function orders()
+    {
+        return $this->hasMany('OrdersModel', ['customer_id' => 'id']);
+    }
+}
+```
+
+Once the relationship is defined, we may retrieve the related record using dynamic properties. Dynamic properties allow you to access relationship methods as if they were properties defined on the model:
+
+```php
+$orders = $this->CustomersModel->findOne(1)->orders;
+```
+
+> The dynamic properties' names are same as methods' names, like [Laravel Eloquent](https://laravel.com/docs/5.7/eloquent-relationships)
+
+For **Querying Relations**, You may query the `orders` relationship and add additional constraints with CI Query Builder to the relationship like so:
+
+```php
+$customer = $this->CustomersModel->findOne(1)
+
+$orders = $customer->orders()->where('active', 1)->get()->result_array();
+```
+
 ### Methods
 
 #### `findOne()`
@@ -721,6 +761,70 @@ This method is called at the end of inserting or updating a active record
 public boolean beforeSave(boolean $insert, array $changedAttributes)
 ```
 
+#### `hasOne()`
+
+Declares a has-one relation
+
+
+```php
+public CI_DB_query_builder hasOne(string $modelName, string $foreignKey=null, string $localKey=null)
+```
+
+*Example:*
+```php
+class OrdersModel extends yidas\Model
+{
+    // ...
+    
+    public function customer()
+    {
+        return $this->hasOne('CustomersModel', 'id', 'customer_id');
+    }
+}
+```
+*Accessing Relational Data:*
+```php
+$this->load->model('OrdersModel');
+// SELECT * FROM `orders` WHERE `id` = 321
+$order = $this->OrdersModel->findOne(321);
+
+// SELECT * FROM `customers` WHERE `is` = 321
+// $customer is a Customers active record
+$customer = $order->customer;
+```
+
+#### `hasMany()`
+
+Declares a has-many relation
+
+
+```php
+public CI_DB_query_builder hasMany(string $modelName, string $foreignKey=null, string $localKey=null)
+```
+
+*Example:*
+```php
+class CustomersModel extends yidas\Model
+{
+    // ...
+    
+    public function orders()
+    {
+        return $this->hasMany('OrdersModel', 'customer_id', 'id');
+    }
+}
+```
+*Accessing Relational Data:*
+```php
+$this->load->model('CustomersModel');
+// SELECT * FROM `customers` WHERE `id` = 123
+$customer = $this->CustomersModel->findOne(123);
+
+// SELECT * FROM `order` WHERE `customer_id` = 123
+// $orders is an array of Orders active records
+$orders = $customer->orders;
+```
+
 #### `toArray()`
 
 Active Record transform to array record

src/Model.php

@@ -525,12 +525,7 @@ public function findOne($condition=[])
             return $record;
         }
 
-        // ORM handling
-        $this->_readProperties = $record;
-        // Primary key condition to ensure single query result 
-        $this->_selfCondition = $record[$this->primaryKey];
-
-        return $this;
+        return $this->createActiveRecord($record, $record[$this->primaryKey]);
     }
 
     /**
@@ -562,14 +557,8 @@ public function findAll($condition=[])
             if (!isset($record[$this->primaryKey])) {
                 throw new Exception("Model's primary key not set", 500); 
             }
-            // Create an ActiveRecord
-            $activeRecord = new static();
-            // ORM handling
-            $activeRecord->_readProperties = $record;
-            // Primary key condition to ensure single query result 
-            $activeRecord->_selfCondition = $record[$this->primaryKey];
-            // Collect
-            $set[] = $activeRecord;
+            // Create an ActiveRecord into collect
+            $set[] = $this->createActiveRecord($record, $record[$this->primaryKey]);
         }
 
         return $set;
@@ -987,6 +976,24 @@ public function withAll()
         return $this;
     }
 
+    /**
+     * New a Active Record from Model by data
+     *
+     * @param array $readProperties
+     * @param array $selfCondition
+     * @return object ActiveRecord(Model)
+     */
+    public function createActiveRecord($readProperties, $selfCondition)
+    {
+        $activeRecord = new static();
+        // ORM handling
+        $activeRecord->_readProperties = $readProperties;
+        // Primary key condition to ensure single query result 
+        $activeRecord->_selfCondition = $selfCondition;
+
+        return $activeRecord;
+    }
+
     /**
      * Active Record (ORM) save for insert or update
      *
@@ -1074,6 +1081,67 @@ public function afterSave($insert, $changedAttributes)
         // overriding
     }
 
+    /**
+     * Declares a has-many relation.
+     *
+     * @param string $modelName The model class name of the related record
+     * @param string $foreignKey 
+     * @param string $localKey
+     * @return object CI_DB_query_builder
+     */
+    public function hasMany($modelName, $foreignKey=null, $localKey=null)
+    {
+        return $this->_relationship($modelName, __FUNCTION__, $foreignKey, $localKey);
+    }
+
+    /**
+     * Declares a has-many relation.
+     *
+     * @param string $modelName The model class name of the related record
+     * @param string $foreignKey 
+     * @param string $localKey
+     * @return object CI_DB_query_builder
+     */
+    public function hasOne($modelName, $foreignKey=null, $localKey=null)
+    {
+        return $this->_relationship($modelName, __FUNCTION__, $foreignKey, $localKey);
+    }
+
+    /**
+     * Base relationship.
+     *
+     * @param string $modelName The model class name of the related record
+     * @param string $relationship
+     * @param string $foreignKey 
+     * @param string $localKey
+     * @return object CI_DB_query_builder
+     */
+    protected function _relationship($modelName, $relationship, $foreignKey=null, $localKey=null)
+    {
+        $this->load->model($modelName);
+
+        $libClass = __CLASS__;
+        
+        // Check if is using same library
+        if (!is_subclass_of($this->$modelName, $libClass)) {
+            throw new Exception("Model `{$modelName}` does not extend {$libClass}", 500);
+        }
+
+        // Keys
+        $foreignKey = ($foreignKey) ? $foreignKey : $this->primaryKey;
+        $localKey = ($localKey) ? $localKey : $this->primaryKey; 
+
+        $query = $this->$modelName->find()
+            ->where($foreignKey, $this->$localKey);
+
+        // Inject Model name into query builder for ORM relationships
+        $query->modelName = $modelName;
+        // Inject relationship type into query builder for ORM relationships
+        $query->relationship = $relationship;
+
+        return $query;
+    }
+
     /**
      * Active Record transform to array record
      *
@@ -1410,6 +1478,33 @@ public function __get($name)
 
             return $this->_readProperties[$name]; 
         }
+        // ORM relationship check
+        else if (method_exists($this, $method = $name)) {
+            
+            $query = call_user_func_array([$this, $method], []);
+
+            // Extract query builder injection property
+            $modelName = isset($query->modelName) ? $query->modelName : null;
+            $relationship = isset($query->relationship) ? $query->relationship : null;
+
+            if (!$modelName || !$relationship) {
+                throw new Exception("ORM relationships error", 500);
+            }
+
+            // Check return type
+            if ($relationship == 'hasOne') {
+
+                // Keep same query builder from hasOne()
+                return $this->$modelName->findOne(null);
+
+            } else {
+
+                // Keep same query builder from hasMany()
+                return $this->$modelName->findAll(null);
+            }
+
+        }
+        // ORM schema check
         else {
 
             $class = get_class($this);