Lines 95.02% 172 / 181
Functions and Methods 81.81% 9 / 11
Classes and Traits 0.00% 0 / 1
Name Lines Functions and Methods CRAP Classes and Traits
HasManyThrough 95.02% 172 / 181 81.81% 9 / 11 52 0.00% 0 / 1
 __construct 100.00% 19 / 19 100.00% 1 / 1 7
 addConstraints 100.00% 41 / 41 100.00% 1 / 1 7
 qualify 100.00% 1 / 1 100.00% 1 / 1 1
 intermediateKeys 46.66% 7 / 15 0.00% 0 / 1 11.46
 secondKeyList 100.00% 1 / 1 100.00% 1 / 1 2
 getSecondKeys 80.00% 4 / 5 0.00% 0 / 1 2.03
 executeResults 100.00% 1 / 1 100.00% 1 / 1 1
 eagerLoad 100.00% 9 / 9 100.00% 1 / 1 3
 eagerLoadChunk 100.00% 70 / 70 100.00% 1 / 1 15
 throughParentAlias 100.00% 1 / 1 100.00% 1 / 1 1
 match 100.00% 18 / 18 100.00% 1 / 1 7
1<?php
2
3declare(strict_types=1);
4
5namespace BlueprintAU\Radiant\Relations;
6
7use BlueprintAU\Radiant\Collection;
8use BlueprintAU\Radiant\Database\Query\WhereBuilder;
9use BlueprintAU\Radiant\Database\Query\Enums\WhereOperator;
10use BlueprintAU\Radiant\Metadata\MetadataFactory;
11use BlueprintAU\Radiant\Model;
12
13/**
14 * A two-hop relation: the parent links to the related model THROUGH an
15 * intermediate model (`Mechanic` has many `Owners` through `Car`).
16 *
17 * The query INNER JOINs the intermediate table: a parent with no
18 * intermediate row legitimately has no through-result, so INNER is the
19 * honest semantics. Joins are a SQL-only feature — a non-SQL connection
20 * throws {@see \BlueprintAU\Radiant\Database\Exceptions\UnsupportedFeatureException}
21 * at execution, mirroring every other join path.
22 *
23 * @template TRelated of Model
24 * @extends Relation<TRelated>
25 * @phpstan-import-type KeyValue from \BlueprintAU\Radiant\Model
26 */
27class HasManyThrough extends Relation
28{
29    /**
30     * The intermediate model bridging parent and related.
31     *
32     * @var class-string<Model>
33     */
34    protected readonly string $through;
35
36    /**
37     * FK on the intermediate table pointing back at the parent.
38     *
39     * @var string|list<string>
40     */
41    protected readonly string|array $firstKey;
42
43    /**
44     * FK on the related table pointing at the intermediate.
45     *
46     * @var string|list<string>
47     */
48    protected readonly string|array $secondKey;
49
50    /**
51     * Create a through relation.
52     *
53     * @param  Model  $parent
54     * @param  class-string<TRelated>  $related
55     * @param  class-string<Model>  $through
56     * @param  string|list<string>  $firstKey
57     * @param  string|list<string>  $secondKey
58     * @param  string|list<string>  $localKey
59     * @throws \InvalidArgumentException
60     */
61    public function __construct(
62        Model $parent,
63        string $related,
64        string $through,
65        string|array $firstKey,
66        string|array $secondKey,
67        string|array $localKey,
68    ) {
69        // The base ctor validates foreignKey↔localKey agreement; the two
70        // hop keys must additionally agree with each other (both scalar or
71        // both composite, matching arity), or the join is unbuildable.
72        if (is_array($firstKey) !== is_array($secondKey)) {
73            throw new \InvalidArgumentException(
74                "A through relation's first and second keys must be BOTH single columns or "
75                . 'BOTH composite column lists; got one of each.'
76            );
77        }
78
79        if (is_array($firstKey) && is_array($secondKey)) {
80            if ($firstKey === [] || $secondKey === []) {
81                throw new \InvalidArgumentException(
82                    "A through relation's composite keys require at least one column; got an empty list."
83                );
84            }
85
86            if (count($firstKey) !== count($secondKey)) {
87                throw new \InvalidArgumentException(
88                    "A through relation's composite first and second keys must have matching "
89                    . 'arity; got ' . count($firstKey) . ' and ' . count($secondKey) . '.'
90                );
91            }
92        }
93
94        $this->through = $through;
95        $this->firstKey = $firstKey;
96        $this->secondKey = $secondKey;
97
98        parent::__construct($parent, $related, $firstKey, $localKey);
99    }
100
101    /**
102     * Constrain the query: join the intermediate table, filter by the
103     * parent's key.
104     *
105     * @return void
106     */
107    protected function addConstraints(): void
108    {
109        $throughTable = $this->through::table();
110        $relatedTable = $this->related::table();
111
112        // The through relation stores the PARENT-side link in the base
113        // relation's key slots: foreignKey = the through table's FK back to
114        // the parent (firstKey), localKey = the parent's own key. The
115        // related→through hop rides $secondKey.
116        $firstKeys = $this->isComposite() ? $this->getForeignKeys() : [$this->getForeignKey()];
117        $secondKeys = $this->secondKeyList();
118        $intermediateKeys = $this->intermediateKeys($secondKeys);
119
120        $this->query = $this->query->join(
121            $throughTable,
122            self::qualify($relatedTable, $secondKeys[0]),
123            '=',
124            self::qualify($throughTable, $intermediateKeys[0]),
125        );
126
127        foreach (array_slice($secondKeys, 1) as $i => $secondKey) {
128            $this->query = $this->query->on(
129                self::qualify($relatedTable, $secondKey),
130                '=',
131                self::qualify($throughTable, $intermediateKeys[$i + 1]),
132            );
133        }
134
135        if (!$this->isComposite()) {
136            $parentKey = $this->parent->attribute($this->getLocalKey());
137
138            if ($parentKey === null) {
139                // Null parent key → no results, without compiling a
140                // meaningless query (BelongsTo's convention).
141                $this->query = $this->query->whereRaw('1 = 0', []);
142                return;
143            }
144
145            $this->query = $this->query->where(
146                self::qualify($throughTable, $firstKeys[0]),
147                '=',
148                $parentKey,
149            );
150
151            return;
152        }
153
154        // The tuple lands inside a whereNested GROUP — the parent filter is
155        // ONE constraint unit: a caller's later `->orWhere(...)` must OR at
156        // the constraint's EDGES, never against the tuple's PARTS. The
157        // values come from the parent's LOCAL key columns (positionally
158        // paired with the first keys) — the first-key names are the THROUGH
159        // table's FK columns and do not exist on the parent.
160        $localKeys = $this->getLocalKeys();
161
162        $this->query = $this->query->whereNested(
163            function (WhereBuilder $nested) use ($throughTable, $firstKeys, $localKeys): WhereBuilder {
164                foreach ($firstKeys as $i => $firstKey) {
165                    $value = $this->parent->attribute($localKeys[$i]);
166                    $nested = $nested->where(
167                        self::qualify($throughTable, $firstKey),
168                        $value === null ? WhereOperator::Null : WhereOperator::Eq,
169                        $value,
170                    );
171                }
172
173                return $nested;
174            }
175        );
176    }
177
178    /**
179     * Qualify a column to its table — `table.column`.
180     *
181     * @param  string  $table
182     * @param  string  $column
183     * @return string
184     */
185    final protected static function qualify(string $table, string $column): string
186    {
187        return $table . '.' . $column;
188    }
189
190    /**
191     * The intermediate table's PK column(s) that the related table's FK
192     * points at.
193     *
194     * @param  list<string>  $secondKeys
195     * @return list<string>
196     * @throws \InvalidArgumentException
197     */
198    protected function intermediateKeys(array $secondKeys): array
199    {
200        $metadata = MetadataFactory::for($this->through);
201        $names = [];
202
203        foreach ($metadata->primaryKeys as $primaryKey) {
204            if ($primaryKey->name === null) {
205                throw new \InvalidArgumentException(
206                    "Through-relation intermediate [{$this->through}] must have a named primary key."
207                );
208            }
209
210            $names[] = $primaryKey->name;
211        }
212
213        if ($names === [] || $secondKeys === [] || count($names) !== count($secondKeys)) {
214            throw new \InvalidArgumentException(
215                "Through-relation intermediate [{$this->through}] has a primary key of "
216                . count($names) . ' column(s); the second key declares ' . count($secondKeys)
217                . ' — the join must pair every key column.'
218            );
219        }
220
221        return $names;
222    }
223
224    /**
225     * The related→through FK columns as a plain list.
226     *
227     * @return list<string>
228     */
229    private function secondKeyList(): array
230    {
231        return is_array($this->secondKey) ? $this->secondKey : [$this->secondKey];
232    }
233
234    /**
235     * The composite form of the related→through FK columns ($secondKey).
236     *
237     * @return list<string>
238     * @throws \LogicException
239     */
240    final public function getSecondKeys(): array
241    {
242        return is_array($this->secondKey)
243            ? $this->secondKey
244            : throw new \LogicException(
245                'This through relation uses a single second key.'
246            );
247    }
248
249    /**
250     * Run the constrained query.
251     *
252     * @return Collection<int, TRelated>
253     */
254    #[\Override]
255    protected function executeResults(): Collection
256    {
257        return $this->query->get();
258    }
259
260    /**
261     * Run the eager query: join the intermediate table for ALL parents at
262     * once, selecting the parent key alongside the related columns.
263     *
264     * @param  list<KeyValue>  $parentKeys
265     * @return EagerResult<TRelated>
266     */
267    #[\Override]
268    public function eagerLoad(array $parentKeys): EagerResult
269    {
270        if ($parentKeys === []) {
271            return EagerResult::fromModels([]);
272        }
273
274        // Chunked: SQL size grows O(parents × arity); driver caps (SQLite
275        // 999 placeholders, MySQL max_allowed_packet) turn an oversized
276        // single query into a hard failure. One query per chunk, merged.
277        $models = [];
278        $parentKeysOut = [];
279
280        foreach (array_chunk($parentKeys, self::EAGER_KEY_CHUNK) as $chunk) {
281            $chunkResult = $this->eagerLoadChunk($chunk);
282            array_push($models, ...$chunkResult->models->all());
283            array_push($parentKeysOut, ...($chunkResult->parentKeys ?? []));
284        }
285
286        return new EagerResult(EagerResult::listToCollection($models), $parentKeysOut);
287    }
288
289    /**
290     * Run one eager-load query for a CHUNK of parent keys.
291     *
292     * @param  list<KeyValue>  $parentKeys
293     * @return EagerResult<TRelated>
294     */
295    #[\Override]
296    protected function eagerLoadChunk(array $parentKeys): EagerResult
297    {
298        $throughTable = $this->through::table();
299        $relatedTable = $this->related::table();
300        $parentFk = self::throughParentAlias($this->related);
301
302        $firstKeys = $this->isComposite() ? $this->getForeignKeys() : [$this->getForeignKey()];
303        $localKeys = $this->isComposite() ? $this->getLocalKeys() : [$this->getLocalKey()];
304        $secondKeys = $this->secondKeyList();
305        $intermediateKeys = $this->intermediateKeys($secondKeys);
306
307        $builder = $this->related::newQuery()
308            ->join(
309                $throughTable,
310                self::qualify($relatedTable, $secondKeys[0]),
311                '=',
312                self::qualify($throughTable, $intermediateKeys[0]),
313            );
314
315        // Subclass ordering hook (HasOneThrough): applies the related-PK
316        // order so first-wins matching stays deterministic, exactly like
317        // the lazy path. No-op for the base many-row relation.
318        $builder = $this->applyEagerOrdering($builder);
319
320        foreach (array_slice($secondKeys, 1) as $i => $secondKey) {
321            $builder = $builder->on(
322                self::qualify($relatedTable, $secondKey),
323                '=',
324                self::qualify($throughTable, $intermediateKeys[$i + 1]),
325            );
326        }
327
328        if (!$this->isComposite()) {
329            $builder = $builder->whereIn(
330                self::qualify($throughTable, $firstKeys[0]),
331                $parentKeys,
332            );
333        } else {
334            // The OR-of-groups lands INSIDE one outer AND-group: the key
335            // set is ONE constraint unit. The related builder auto-applies
336            // trait scopes (e.g. soft-delete `deleted_at IS NULL`) as
337            // leading AND-groups — flat top-level ORs would compile to
338            // `(scope) OR (fk = ? AND ...) OR ...` and let a scope-excluded
339            // row back in whenever its key matched. Grouped, the scope
340            // ANDs against the whole set.
341            $builder = $builder->whereNested(
342                function (WhereBuilder $nested) use ($throughTable, $firstKeys, $localKeys, $parentKeys): WhereBuilder {
343                    $grouped = $nested;
344
345                    foreach ($parentKeys as $parentKey) {
346                        if (!is_array($parentKey)) {
347                            throw new \InvalidArgumentException(
348                                'A composite through-relation key requires column => value key maps '
349                                . 'for eager loading; got ' . get_debug_type($parentKey) . '.'
350                            );
351                        }
352
353                        $grouped = $grouped->orWhereNested(
354                            function (WhereBuilder $keyGroup) use ($throughTable, $firstKeys, $localKeys, $parentKey): WhereBuilder {
355                                foreach ($firstKeys as $i => $firstKey) {
356                                    // The key map is keyed by the parent's
357                                    // LOCAL key columns (what the loader
358                                    // collects); the constraint targets the
359                                    // THROUGH table's first-key columns.
360                                    $value = $parentKey[$localKeys[$i]] ?? null;
361                                    $keyGroup = $keyGroup->where(
362                                        self::qualify($throughTable, $firstKey),
363                                        $value === null ? WhereOperator::Null : WhereOperator::Eq,
364                                        $value,
365                                    );
366                                }
367
368                                return $keyGroup;
369                            }
370                        );
371                    }
372
373                    return $grouped;
374                }
375            );
376        }
377
378        // Columns are plain (qualified) specs with the standard `as`
379        // alias — the Grammar wraps them like any other column list. The
380        // parent-key select carries EVERY first-key column, aliased to
381        // the namespaced synthetic alias per column when composite.
382        $selects = [];
383
384        foreach ($firstKeys as $firstKey) {
385            $selects[] = self::qualify($throughTable, $firstKey)
386                . ' as '
387                . ($firstKeys[0] === $firstKey ? $parentFk : $parentFk . '_' . $firstKey);
388        }
389
390        $selects[] = "{$relatedTable}.*";
391
392        $builder = $builder->select(...$selects);
393
394        $rows = $builder->getRaw();
395
396        $keys = [];
397        $models = [];
398
399        foreach ($rows->all() as $row) {
400            if (!$this->isComposite()) {
401                $keys[] = $row->{$parentFk} ?? null;
402            } else {
403                $tuple = [];
404
405                foreach ($firstKeys as $firstKey) {
406                    $column = $firstKeys[0] === $firstKey ? $parentFk : $parentFk . '_' . $firstKey;
407                    $tuple[] = $row->{$column} ?? null;
408                }
409
410                $keys[] = $tuple;
411            }
412
413            $models[] = $this->related::fromRow($row);
414        }
415
416        return new EagerResult(EagerResult::listToCollection($models), $keys);
417    }
418
419    /**
420     * The synthetic alias carrying the parent key through the join.
421     *
422     * @param  class-string<Model>  $related
423     * @return string
424     */
425    private static function throughParentAlias(string $related): string
426    {
427        return 'radiant_through_parent_' . $related::table();
428    }
429
430    /**
431     * Distribute eager results onto parents, grouped by the parent key
432     * carried on the {@see EagerResult}.
433     *
434     * @param  list<Model>  $parents
435     * @param  Collection<int, TRelated>  $results
436     * @param  string  $name
437     * @param  list<int|string|null|list<int|string|null>>|null  $eagerParentKeys
438     * @return void
439     */
440    public function match(array $parents, Collection $results, string $name, ?array $eagerParentKeys = null): void
441    {
442        if ($eagerParentKeys === null) {
443            // A caller matched WITHOUT the eager-load context — the per-row
444            // keys are unavailable. Fail loudly: silently matching by
445            // re-querying (or matching nothing) would hide the contract.
446            throw new \LogicException(
447                static::class . '::match() requires the EagerResult parent keys; '
448                . 'call it with the array returned by eagerLoad(), not the models alone.'
449            );
450        }
451
452        $grouped = [];
453
454        foreach ($results as $i => $model) {
455            $parentKey = $eagerParentKeys[$i] ?? null;
456
457            if ($parentKey === null) {
458                continue;
459            }
460
461            $grouped[self::serializeKey($parentKey)][] = $model;
462        }
463
464        $localKeys = $this->isComposite() ? $this->getLocalKeys() : [$this->getLocalKey()];
465
466        foreach ($parents as $parent) {
467            $key = $this->isComposite()
468                ? self::tupleValues($parent, $localKeys)
469                : $parent->attribute($localKeys[0]);
470            // The bag's items came off $results (TRelated) — every one IS
471            // a Model; setRelation accepts Collection<int, Model> and the item
472            // template is not covariant.
473            /** @var Collection<int, Model> $bag */
474            $bag = Collection::make($grouped[self::serializeKey($key)] ?? []);
475            $parent->setRelation($name, $bag);
476        }
477    }
478}