add through relation

Author: michalsn

.php-cs-fixer.dist.php

@@ -0,0 +1,32 @@
+<?php
+
+use CodeIgniter\CodingStandard\CodeIgniter4;
+use Nexus\CsConfig\Factory;
+use PhpCsFixer\Finder;
+
+$finder = Finder::create()
+    ->files()
+    ->in([
+        __DIR__ . '/src/',
+        __DIR__ . '/tests/',
+    ])
+    ->exclude([
+        'build',
+        'Views',
+    ])
+    ->append([
+        __FILE__,
+        __DIR__ . '/rector.php',
+    ]);
+
+$overrides = [
+    // 'declare_strict_types' => true,
+    // 'void_return'          => true,
+];
+
+$options = [
+    'finder'    => $finder,
+    'cacheFile' => 'build/.php-cs-fixer.cache',
+];
+
+return Factory::create(new CodeIgniter4(), $overrides, $options)->forProjects();

composer.json

@@ -24,7 +24,8 @@
     "autoload": {
         "psr-4": {
             "Michalsn\\CodeIgniterNestedModel\\": "src"
-        }
+        },
+        "files": ["src/Common.php"]
     },
     "autoload-dev": {
         "psr-4": {

docs/installation.md

@@ -15,7 +15,7 @@ composer require michalsn/codeigniter-nested-model
 
 In the example below we will assume that files from this project will be located in `app/ThirdParty/nested-model` directory.
 
-Download this project and then enable it by editing the `app/Config/Autoload.php` file and adding the `Michalsn\CodeIgniterNestedModel` namespace to the `$psr4` array, like in the below example:
+Download this project and then enable it by editing the `app/Config/Autoload.php` file and adding the `Michalsn\CodeIgniterNestedModel` namespace to the `$psr4` array. You also have to add `Common.php` to the `$files` array, like in the below example:
 
 ```php
 <?php
@@ -28,4 +28,11 @@ public $psr4 = [
 ];
 
 // ...
+
+public $files = [
+    APPPATH . 'ThirdParty/nested-model/src/Common.php',
+];
+
+// ...
+
 ```

docs/relations.md

@@ -1,11 +1,13 @@
 # Relations
 
-- [One-to-one](#one-to-one)
-- [One-to-many](#one-to-many)
-- [One-to-many inverse](#one-to-many-inverse)
-- [One-of-many](#one-of-many)
+- [One to one](#one-to-one)
+- [One to many](#one-to-many)
+- [One to many inverse](#one-to-many-inverse)
+- [One of many](#one-of-many)
+- [Has one through](#has-one-through)
+- [Has many through](#has-many-through)
 
-## One-to-one
+## One to one
 
 A one-to-one relationship where one model is associated with exactly one instance of another model.
 
@@ -38,7 +40,7 @@ class UserModel extends Model
 model(UserModel::class)->with('profile')->find(1);
 ```
 
-## One-to-many
+## One to many
 
 A one-to-many relationship where one model is associated with multiple instances of another model.
 
@@ -71,7 +73,7 @@ class UserModel extends Model
 model(UserModel::class)->with('posts')->find(1);
 ```
 
-## One-to-many inverse
+## One to many inverse
 
 A one-to-many inverse relationship where a model belongs to another model.
 
@@ -104,7 +106,7 @@ class PostModel extends Model
 model(PostModel::class)->with('user')->find(1);
 ```
 
-## One-of-many
+## One of many
 
 A specialized type of one-to-one relationship where a parent model has multiple related records, but only one of them is considered active or relevant at any given time, based on a specific condition (e.g., the most recent, the highest priority, or the one meeting a custom criterion).
 
@@ -157,3 +159,73 @@ model(UserModel::class)->with('firstPost')->find(1);
 
 model(UserModel::class)->with('bestPost')->find(1);
 ```
+
+## Has one through
+
+A one-to-one relationship that is linked through an intermediate model. This means the parent model is related to a single record in the final model through another model acting as a bridge.
+
+### Example
+
+Consider an application where:
+
+- A **User** belongs to a **Company**.
+- Each **Company** has an **Address**.
+
+You want to retrieve a User's Address without needing to manually query through the Company.
+
+```php
+class UserModel extends Model
+{
+    use HasRelations;
+
+    // ...
+
+    public function initialize()
+    {
+        $this->initRelations();
+    }
+
+    public function address(): Relation
+    {
+        return $this->hasOneThrough(AddressModel::class, CompanyModel::class);
+    }
+}
+```
+
+### Usage
+
+```php
+model(UserModel::class)->with('address')->find(1);
+```
+
+## Has many through
+
+A one-to-many relationship that is linked through an intermediate model. This means the parent model is related to multiple records in the final model through another model acting as a bridge.
+
+### Example
+
+Consider an application where::
+
+- A *Country* has many *Users*.
+- A *User* has many *Posts*.
+
+You want to fetch all Posts for a Country, even though the Posts table does not directly reference the Country.
+
+```php
+class CountryModel extends Model
+{
+    use HasRelations;
+
+    // ...
+
+    public function initialize()
+    {
+        $this->initRelations();
+    }
+
+    public function posts(): Relation
+    {
+        return $this->hasManyThrough(PostModel::class, UserModel::class);
+    }
+}
+```

src/Common.php

@@ -0,0 +1,35 @@
+<?php
+
+use CodeIgniter\Model;
+
+if (! function_exists('get_foreign_key')) {
+    /**
+     * Get foreign key based on model info.
+     */
+    function get_foreign_key(Model $model): string
+    {
+        $refObj = new ReflectionObject($model);
+
+        $refProp = $refObj->getProperty('table');
+        $table   = $refProp->getValue($model);
+
+        $refProp    = $refObj->getProperty('primaryKey');
+        $primaryKey = $refProp->getValue($model);
+
+        return singular($table) . '_' . $primaryKey;
+    }
+}
+
+if (! function_exists('get_primary_key')) {
+    /**
+     * Get primary key based on model info.
+     */
+    function get_primary_key(Model $model): string
+    {
+        $refObj = new ReflectionObject($model);
+
+        $refProp = $refObj->getProperty('primaryKey');
+
+        return $refProp->getValue($model);
+    }
+}

src/Language/en/NestedModel.php

@@ -1,9 +1,9 @@
 <?php
 
 return [
-    'methodNotSupported' => 'This method is not supported for the "{0}" relation.',
+    'methodNotSupported'        => 'This method is not supported for the "{0}" relation.',
     'parentRelationNotDeclared' => 'Parent relation "{0}" has not been declared yet.',
-    'relationNotDefined' => 'Relation "{0}" is not defined.',
-    'missingReturnType' => 'Method "{0}()" is missing a required return type declaration.',
-    'incorrectReturnType' => 'Method "{0}()" returned an incorrect type.'
+    'relationNotDefined'        => 'Relation "{0}" is not defined.',
+    'missingReturnType'         => 'Method "{0}()" is missing a required return type declaration.',
+    'incorrectReturnType'       => 'Method "{0}()" returned an incorrect type.',
 ];

src/Relation.php

@@ -4,7 +4,6 @@
 
 namespace Michalsn\CodeIgniterNestedModel;
 
-use BadMethodCallException;
 use Closure;
 use CodeIgniter\Entity\Entity;
 use CodeIgniter\Model;
@@ -17,6 +16,7 @@ class Relation
 {
     private ?Closure $conditions = null;
     private ?OfMany $ofMany      = null;
+    private ?Through $through    = null;
 
     /**
      * @var list<With>
@@ -98,7 +98,63 @@ public function applyWith(): static
         return $this;
     }
 
-    public function getOfMany(): OfMany
+    public function setThrough(Model $model, ?string $foreignKey = null, ?string $primaryKey = null): static
+    {
+        $this->through = new Through(
+            $model,
+            $foreignKey ?? get_foreign_key($model),
+            $primaryKey ?? get_primary_key($model)
+        );
+
+        return $this;
+    }
+
+    public function hasThrough(): bool
+    {
+        return $this->through !== null;
+    }
+
+    public function applyThrough(array $id, string $primaryKey): static
+    {
+        if ($this->through === null) {
+            $this->model->whereIn(
+                sprintf(
+                    '%s.%s',
+                    $this->model->getTable(),
+                    $this->foreignKey
+                ),
+                $id
+            );
+
+            return $this;
+        }
+
+        $this->model
+            ->select(sprintf('%s.*', $this->model->getTable()))
+            ->join(
+                $this->through->model->getTable(),
+                sprintf(
+                    '%s.%s = %s.%s',
+                    $this->through->model->getTable(),
+                    $this->through->foreignKey,
+                    $this->model->getTable(),
+                    $this->primaryKey
+                ),
+                'LEFT'
+            )
+            ->whereIn(
+                sprintf(
+                    '%s.%s',
+                    $this->through->model->getTable(),
+                    $primaryKey
+                ),
+                $id
+            );
+
+        return $this;
+    }
+
+    public function getOfMany(): ?OfMany
     {
         return $this->ofMany;
     }

src/Through.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Michalsn\CodeIgniterNestedModel;
+
+use CodeIgniter\Model;
+
+readonly class Through
+{
+    public function __construct(public Model $model, public string $foreignKey, public string $primaryKey)
+    {
+    }
+}