feat(database): add support for hasmanythrough relation (#2052)

Author: laylatichy

docs/1-essentials/03-database.md

@@ -293,6 +293,30 @@ public ?Address $address = null;
 - `throughOwnerJoin`: FK on the target table pointing to the intermediate
 - `throughRelationJoin`: PK on the intermediate table
 
+### Has many through
+
+The {b`#[Tempest\Database\HasManyThrough]`} attribute defines a one-to-many relationship that traverses an intermediate model. This lets you access a collection of distant relations directly, resolved in a single SQL query with two JOINs.
+
+```php
+use Tempest\Database\HasManyThrough;
+
+final class Author
+{
+    /** @var \App\Payment\Payment[] */
+    #[HasManyThrough(Contract::class)]
+    public array $payments = [];
+}
+```
+
+The `through` parameter specifies the intermediate model class. The target model is inferred from the docblock's array type. This generates SQL like:
+
+```sql
+LEFT JOIN contracts ON contracts.author_id = authors.id
+LEFT JOIN payments ON payments.contract_id = contracts.id
+```
+
+The same optional parameters as `HasOneThrough` are available for custom join fields: `ownerJoin`, `relationJoin`, `throughOwnerJoin`, and `throughRelationJoin`.
+
 ### Using UUIDs as primary keys
 
 By default, Tempest uses auto-incrementing integers as primary keys. UUIDs can be used as primary keys instead by annotating the {b`Tempest\Database\PrimaryKey`} property with the {b`#[Tempest\Database\Uuid]`} attribute. Tempest automatically generates a UUID v7 when a new model is created:

packages/database/src/Builder/ModelInspector.php

@@ -7,6 +7,7 @@
 use Tempest\Database\Config\DatabaseConfig;
 use Tempest\Database\Eager;
 use Tempest\Database\HasMany;
+use Tempest\Database\HasManyThrough;
 use Tempest\Database\HasOne;
 use Tempest\Database\HasOneThrough;
 use Tempest\Database\PrimaryKey;
@@ -54,6 +55,7 @@ public static function forModel(object|string $model): self
         $key = match (true) {
             is_string($model) => $model,
             $model instanceof HasMany => $model->property->getIterableType()->getName(),
+            $model instanceof HasManyThrough => $model->property->getIterableType()->getName(),
             $model instanceof BelongsTo => $model->property->getType()->getName(),
             $model instanceof HasOne => $model->property->getType()->getName(),
             $model instanceof HasOneThrough => $model->property->getType()->getName(),
@@ -71,7 +73,7 @@ public static function forModel(object|string $model): self
     public function __construct(
         private(set) object|string $model,
     ) {
-        if ($model instanceof HasMany) {
+        if ($model instanceof HasMany || $model instanceof HasManyThrough) {
             $model = $model->property->getIterableType()->asClass();
             $this->reflector = $model;
         } elseif ($model instanceof BelongsTo || $model instanceof HasOne || $model instanceof HasOneThrough) {
@@ -164,6 +166,10 @@ public function getPropertyValues(): array
                     continue;
                 }
 
+                if ($this->getHasManyThrough($property->getName()) instanceof HasManyThrough) {
+                    continue;
+                }
+
                 $name = $property->getName();
 
                 $values[$name] = $property->getValue($this->instance);
@@ -222,6 +228,10 @@ public function getBelongsTo(string $name): ?BelongsTo
                 return null;
             }
 
+            if ($property->hasAttribute(HasManyThrough::class)) {
+                return null;
+            }
+
             $belongsTo = new BelongsTo();
             $belongsTo->property = $property;
 
@@ -277,6 +287,10 @@ public function getHasMany(string $name): ?HasMany
                 return $hasMany;
             }
 
+            if ($property->hasAttribute(HasManyThrough::class)) {
+                return null;
+            }
+
             if ($property->hasAttribute(Virtual::class)) {
                 return null;
             }
@@ -321,6 +335,29 @@ public function getHasOneThrough(string $name): ?HasOneThrough
         });
     }
 
+    public function getHasManyThrough(string $name): ?HasManyThrough
+    {
+        return $this->memoize('getHasManyThrough' . $name, function () use ($name) {
+            if (! $this->isObjectModel()) {
+                return null;
+            }
+
+            $name = str($name)->camel();
+
+            if (! $this->reflector->hasProperty($name)) {
+                return null;
+            }
+
+            $property = $this->reflector->getProperty($name);
+
+            if (($hasManyThrough = $property->getAttribute(HasManyThrough::class)) instanceof HasManyThrough) {
+                return $hasManyThrough;
+            }
+
+            return null;
+        });
+    }
+
     public function isRelation(string|PropertyReflector $name): bool
     {
         $name = $name instanceof PropertyReflector ? $name->getName() : $name;
@@ -332,6 +369,7 @@ public function isRelation(string|PropertyReflector $name): bool
                 || $this->getHasOne($name) instanceof HasOne
                 || $this->getHasMany($name) instanceof HasMany
                 || $this->getHasOneThrough($name) instanceof HasOneThrough
+                || $this->getHasManyThrough($name) instanceof HasManyThrough
             ),
         );
     }
@@ -340,7 +378,10 @@ public function getRelation(string|PropertyReflector $name): ?Relation
     {
         $name = $name instanceof PropertyReflector ? $name->getName() : $name;
 
-        return $this->memoize('getRelation' . $name, fn () => $this->getBelongsTo($name) ?? $this->getHasOne($name) ?? $this->getHasMany($name) ?? $this->getHasOneThrough($name));
+        return $this->memoize(
+            'getRelation' . $name,
+            fn () => $this->getBelongsTo($name) ?? $this->getHasOne($name) ?? $this->getHasMany($name) ?? $this->getHasOneThrough($name) ?? $this->getHasManyThrough($name),
+        );
     }
 
     /**
@@ -444,6 +485,10 @@ public function getSelectFields(): ImmutableArray
                 continue;
             }
 
+            if ($relation instanceof HasManyThrough) {
+                continue;
+            }
+
             if ($property->isVirtual()) {
                 continue;
             }