add belongsToMany relation

Author: michalsn

composer.lock

@@ -229,3 +229,67 @@ class CountryModel extends Model
     }
 }
 ```
+
+### Usage
+
+```php
+model(UserModel::class)->with('posts')->find(1);
+```
+
+## Many to many
+
+A `belongsToMany` relationship is used for many-to-many associations between two models. This relationship involves an intermediate pivot table that links records in one table to records in another.
+
+### Example
+
+Consider an application where:
+
+- *Students* can enroll in multiple *Courses*.
+- A *Course* can have multiple *Students*.
+
+Since both Students and Courses can be related to each other in many ways, we use a pivot table to manage this association.
+
+```php
+class StudentModel extends Model
+{
+    use HasRelations;
+
+    // ...
+
+    public function initialize()
+    {
+        $this->initRelations();
+    }
+
+    public function courses(): Relation
+    {
+        return $this->belongsToMany(CourseModel::class);
+    }
+}
+```
+```php
+class CourseModel extends Model
+{
+    use HasRelations;
+
+    // ...
+
+    public function initialize()
+    {
+        $this->initRelations();
+    }
+
+    public function students(): Relation
+    {
+        return $this->belongsToMany(StudentModel::class);
+    }
+}
+```
+
+### Usage
+
+```php
+model(StudentModel::class)->with('courses')->find(1);
+
+model(CourseModel::class)->with('students')->find(1);
+```

docs/relations.md

@@ -9,4 +9,5 @@ enum RelationTypes
     case hasOne;
     case hasMany;
     case belongsTo;
+    case belongsToMany;
 }

src/Enums/RelationTypes.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Michalsn\CodeIgniterNestedModel;
+
+readonly class Many
+{
+    public function __construct(public string $pivotTable, public string $pivotForeignKey, public string $pivotRelatedKey)
+    {
+    }
+}

src/Many.php

@@ -17,6 +17,7 @@ class Relation
     private ?Closure $conditions = null;
     private ?OfMany $ofMany      = null;
     private ?Through $through    = null;
+    private ?Many $many          = null;
 
     /**
      * @var list<With>
@@ -114,42 +115,92 @@ public function hasThrough(): bool
         return $this->through !== null;
     }
 
-    public function applyThrough(array $id, string $primaryKey): static
+    public function setMany(string $pivotTable, string $pivotForeignKey, string $pivotRelatedKey): static
     {
-        if ($this->through === null) {
-            $this->model->whereIn(
-                sprintf(
-                    '%s.%s',
-                    $this->model->getTable(),
-                    $this->foreignKey
-                ),
-                $id
-            );
+        $this->many = new Many($pivotTable, $pivotForeignKey, $pivotRelatedKey);
+
+        return $this;
+    }
+
+    public function hasMany(): bool
+    {
+        return $this->many !== null;
+    }
+
+    public function getMany(): ?Many
+    {
+        return $this->many;
+    }
+
+    public function applyRelation(array $id, string $primaryKey): static
+    {
+        if ($this->through !== null) {
+            $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;
         }
 
-        $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
-            );
+        if ($this->many !== null) {
+            $this->model
+                ->select(
+                    sprintf(
+                        '%s.*, %s.%s',
+                        $this->model->getTable(),
+                        $this->many->pivotTable,
+                        $this->many->pivotForeignKey
+                    )
+                )
+                ->join(
+                    $this->many->pivotTable,
+                    sprintf(
+                        '%s.%s = %s.%s',
+                        $this->many->pivotTable,
+                        $this->many->pivotRelatedKey,
+                        $this->model->getTable(),
+                        get_primary_key($this->model)
+                    ),
+                    'LEFT'
+                )
+                ->whereIn(
+                    sprintf(
+                        '%s.%s',
+                        $this->many->pivotTable,
+                        $this->many->pivotForeignKey
+                    ),
+                    $id
+                );
+
+            return $this;
+        }
+
+        $this->model->whereIn(
+            sprintf(
+                '%s.%s',
+                $this->model->getTable(),
+                $this->foreignKey
+            ),
+            $id
+        );
 
         return $this;
     }
@@ -208,4 +259,36 @@ private function getOrderField(Model $model): string
 
         return $refProp->getValue($model);
     }
+
+    public function filterResult(array|Entity $row, string $returnType): array|Entity
+    {
+        if ($row === [] || $this->type !== RelationTypes::belongsToMany) {
+            return $row;
+        }
+
+        if ($returnType === 'array') {
+            unset($row[$this->many->pivotForeignKey]);
+        } else {
+            unset($row->{$this->many->pivotForeignKey});
+        }
+
+        return $row;
+    }
+
+    public function filterResults(array|Entity $results, string $returnType): array|Entity
+    {
+        if ($this->type !== RelationTypes::belongsToMany) {
+            return $results;
+        }
+
+        foreach ($results as &$row) {
+            if ($returnType === 'array') {
+                unset($row[$this->many->pivotForeignKey]);
+            } else {
+                unset($row->{$this->many->pivotForeignKey});
+            }
+        }
+
+        return $results;
+    }
 }

src/Relation.php

@@ -39,12 +39,21 @@ private function handleRelation(string $name)
 
         $relation = $model->{$name}();
 
-        $relation->model->where($relation->foreignKey, $this->attributes[$relation->primaryKey]);
-
         if (in_array($relation->type, [RelationTypes::hasOne, RelationTypes::belongsTo], true)) {
-            $this->attributes[$name] = $relation->model->first();
+            $row = $this->attributes[$name] = $relation->filterResult(
+                $relation
+                    ->applyRelation([$this->attributes[$relation->primaryKey]], $relation->foreignKey)
+                    ->model
+                    ->first(),
+                'object'
+            );
         } else {
-            $this->attributes[$name] = $relation->model->findAll();
+            $this->attributes[$name] = $relation->filterResults(
+                $relation->applyRelation([$this->attributes[$relation->primaryKey]], $relation->foreignKey)
+                    ->model
+                    ->findAll(),
+                'object'
+            );
         }
 
         return $this->attributes[$name];