Debian Codegraph @

vendor/ipl/orm/src/Resolver.php

raw
1 <?php
2
3 namespace ipl\Orm;
4
5 use AppendIterator;
6 use ArrayIterator;
7 use Generator;
8 use InvalidArgumentException;
9 use ipl\Orm\Contract\QueryAwareBehavior;
10 use ipl\Orm\Exception\InvalidColumnException;
11 use ipl\Orm\Exception\InvalidRelationException;
12 use ipl\Orm\Relation\BelongsToMany;
13 use ipl\Sql\ExpressionInterface;
14 use LogicException;
15 use OutOfBoundsException;
16 use SplObjectStorage;
17
18 /**
19 * Column and relation resolver. Acts as glue between queries and models
20 */
21 class Resolver
22 {
23 /** @var Query The query to resolve */
24 protected Query $query;
25
26 /** @var SplObjectStorage Model relations */
27 protected SplObjectStorage $relations;
28
29 /** @var SplObjectStorage Model behaviors */
30 protected SplObjectStorage $behaviors;
31
32 /** @var SplObjectStorage Model defaults */
33 protected SplObjectStorage $defaults;
34
35 /** @var SplObjectStorage Model aliases */
36 protected SplObjectStorage $aliases;
37
38 /** @var ?string The alias prefix to use */
39 protected ?string $aliasPrefix = null;
40
41 /** @var SplObjectStorage Selectable columns from resolved models */
42 protected SplObjectStorage $selectableColumns;
43
44 /** @var SplObjectStorage Select columns from resolved models */
45 protected SplObjectStorage $selectColumns;
46
47 /** @var SplObjectStorage Meta data from models and their direct relations */
48 protected SplObjectStorage $metaData;
49
50 /** @var SplObjectStorage Resolved relations */
51 protected SplObjectStorage $resolvedRelations;
52
53 /**
54 * Create a new resolver
55 *
56 * @param Query $query The query to resolve
57 */
58 public function __construct(Query $query)
59 {
60 $this->query = $query;
61
62 $this->relations = new SplObjectStorage();
63 $this->behaviors = new SplObjectStorage();
64 $this->defaults = new SplObjectStorage();
65 $this->aliases = new SplObjectStorage();
66 $this->selectableColumns = new SplObjectStorage();
67 $this->selectColumns = new SplObjectStorage();
68 $this->metaData = new SplObjectStorage();
69 $this->resolvedRelations = new SplObjectStorage();
70 }
71
72 /**
73 * Get a model's relations
74 *
75 * @param Model $model
76 *
77 * @return Relations
78 */
79 public function getRelations(Model $model): Relations
80 {
81 if (! $this->relations->offsetExists($model)) {
82 $relations = new Relations();
83 $model->createRelations($relations);
84 $this->relations->offsetSet($model, $relations);
85 }
86
87 return $this->relations[$model];
88 }
89
90 /**
91 * Get a model's behaviors
92 *
93 * @param Model $model
94 *
95 * @return Behaviors
96 */
97 public function getBehaviors(Model $model): Behaviors
98 {
99 if (! $this->behaviors->offsetExists($model)) {
100 $behaviors = new Behaviors();
101 $model->createBehaviors($behaviors);
102 $this->behaviors->offsetSet($model, $behaviors);
103
104 foreach ($behaviors as $behavior) {
105 if ($behavior instanceof QueryAwareBehavior) {
106 $behavior->setQuery($this->query);
107 }
108 }
109 }
110
111 return $this->behaviors[$model];
112 }
113
114 /**
115 * Get a model's defaults
116 *
117 * @param Model $model
118 *
119 * @return Defaults
120 */
121 public function getDefaults(Model $model): Defaults
122 {
123 if (! $this->defaults->offsetExists($model)) {
124 $defaults = new Defaults();
125 $model->createDefaults($defaults);
126 $this->defaults->offsetSet($model, $defaults);
127 }
128
129 return $this->defaults[$model];
130 }
131
132 /**
133 * Get a model alias
134 *
135 * @param Model $model
136 *
137 * @return string
138 *
139 * @throws OutOfBoundsException If no alias exists for the given model
140 */
141 public function getAlias(Model $model): string
142 {
143 if (! $this->aliases->offsetExists($model)) {
144 throw new OutOfBoundsException(sprintf(
145 "Can't get alias for model '%s'. Alias does not exist",
146 get_class($model)
147 ));
148 }
149
150 return $this->aliasPrefix . $this->aliases[$model];
151 }
152
153 /**
154 * Set a model alias
155 *
156 * @param Model $model
157 * @param string $alias
158 *
159 * @return $this
160 */
161 public function setAlias(Model $model, string $alias): static
162 {
163 $this->aliases[$model] = $alias;
164
165 return $this;
166 }
167
168 /**
169 * Get the alias prefix
170 *
171 * @return ?string
172 */
173 public function getAliasPrefix(): ?string
174 {
175 return $this->aliasPrefix;
176 }
177
178 /**
179 * Set the alias prefix
180 *
181 * @param string $alias
182 *
183 * @return $this
184 */
185 public function setAliasPrefix(string $alias): static
186 {
187 $this->aliasPrefix = $alias;
188
189 return $this;
190 }
191
192 /**
193 * Get whether the specified model provides the given selectable column
194 *
195 * @param Model $subject
196 * @param string $column
197 *
198 * @return bool
199 */
200 public function hasSelectableColumn(Model $subject, string $column): bool
201 {
202 if (! $this->selectableColumns->offsetExists($subject)) {
203 $this->collectColumns($subject);
204 }
205
206 $columns = $this->selectableColumns[$subject];
207 if (! isset($columns[$column])) {
208 $columns[$column] = $this->getBehaviors($subject)->isSelectableColumn($column);
209 }
210
211 return $columns[$column];
212 }
213
214 /**
215 * Get all selectable columns from the given model
216 *
217 * @param Model $subject
218 *
219 * @return array
220 */
221 public function getSelectableColumns(Model $subject): array
222 {
223 if (! $this->selectableColumns->offsetExists($subject)) {
224 $this->collectColumns($subject);
225 }
226
227 return array_keys($this->selectableColumns[$subject]);
228 }
229
230 /**
231 * Get all select columns from the given model
232 *
233 * @param Model $subject
234 *
235 * @return array Select columns suitable for {@link \ipl\Sql\Select::columns()}
236 */
237 public function getSelectColumns(Model $subject): array
238 {
239 if (! $this->selectColumns->offsetExists($subject)) {
240 $this->collectColumns($subject);
241 }
242
243 return $this->selectColumns[$subject];
244 }
245
246 /**
247 * Get all meta data from the given model and its direct relations
248 *
249 * @param Model $subject
250 *
251 * @return array Column paths as keys (relative to $subject) and their meta data as values
252 */
253 public function getColumnDefinitions(Model $subject): array
254 {
255 if (! $this->metaData->offsetExists($subject)) {
256 $this->metaData->offsetSet($subject, $this->collectMetaData($subject));
257 }
258
259 return $this->metaData[$subject];
260 }
261
262 /**
263 * Get definition of the given column
264 *
265 * @param string $columnPath
266 *
267 * @return ColumnDefinition
268 */
269 public function getColumnDefinition(string $columnPath): ColumnDefinition
270 {
271 $parts = explode('.', $columnPath);
272 $model = $this->query->getModel();
273
274 if ($parts[0] !== $model->getTableAlias()) {
275 array_unshift($parts, $model->getTableAlias());
276 }
277
278 do {
279 $relationPath[] = array_shift($parts);
280 $column = implode('.', $parts);
281
282 if (count($relationPath) === 1) {
283 $subject = $model;
284 } else {
285 $subject = $this->resolveRelation(implode('.', $relationPath))->getTarget();
286 }
287
288 if ($this->hasSelectableColumn($subject, $column)) {
289 break;
290 }
291 } while ($parts);
292
293 $definition = $this->getColumnDefinitions($subject)[$column] ?? new ColumnDefinition($column);
294 $this->getBehaviors($subject)->rewriteColumnDefinition($definition, implode('.', $relationPath));
295
296 return $definition;
297 }
298
299 /**
300 * Qualify the given alias by the specified table name
301 *
302 * @param string $alias
303 * @param string $tableName
304 *
305 * @return string
306 */
307 public function qualifyColumnAlias(string $alias, string $tableName): string
308 {
309 return $tableName . '_' . $alias;
310 }
311
312 /**
313 * Qualify the given column by the specified table name
314 *
315 * @param string $column
316 * @param string $tableName
317 *
318 * @return string
319 */
320 public function qualifyColumn(string $column, string $tableName): string
321 {
322 return $tableName . '.' . $column;
323 }
324
325 /**
326 * Qualify the given columns by the specified model
327 *
328 * @param iterable $columns
329 * @param ?Model $model Leave null in case $columns is {@see Resolver::requireAndResolveColumns()}
330 *
331 * @return array
332 *
333 * @throws InvalidArgumentException If $model is not passed and $columns is not a generator
334 */
335 public function qualifyColumns(iterable $columns, ?Model $model = null): array
336 {
337 $target = $model ?: $this->query->getModel();
338 $targetAlias = $this->getAlias($target);
339
340 $qualified = [];
341 foreach ($columns as $alias => $column) {
342 if (is_int($alias) && is_array($column)) {
343 // $columns is $this->requireAndResolveColumns()
344 [$target, $alias, $columnName] = $column;
345 $targetAlias = $this->getAlias($target);
346
347 // Thanks to PHP 5.6 where `list` is evaluated from right to left. It will extract
348 // the values for `$target` and `$alias` then from the third argument (`$column`).
349 $column = $columnName;
350 } elseif ($target === null) {
351 throw new InvalidArgumentException(
352 'Passing no model is only possible if $columns is a generator'
353 );
354 }
355
356 if ($column instanceof ResolvedExpression) {
357 $column->setColumns($this->qualifyColumns($column->getResolvedColumns()));
358 } elseif ($column instanceof ExpressionInterface) {
359 $column = clone $column; // The expression may be part of a model and those shouldn't change implicitly
360 $column->setColumns($this->qualifyColumns($column->getColumns(), $target));
361 } else {
362 $column = $this->qualifyColumn($column, $targetAlias);
363 }
364
365 $qualified[$alias] = $column;
366 }
367
368 return $qualified;
369 }
370
371 /**
372 * Qualify the given columns and aliases by the specified model
373 *
374 * @param iterable $columns
375 * @param ?Model $model Leave null in case $columns is {@see Resolver::requireAndResolveColumns()}
376 * @param bool $autoAlias Set an alias for columns which have none
377 *
378 * @return array
379 *
380 * @throws InvalidArgumentException If $model is not passed and $columns is not a generator
381 */
382 public function qualifyColumnsAndAliases(iterable $columns, ?Model $model = null, bool $autoAlias = true): array
383 {
384 $target = $model ?: $this->query->getModel();
385 $targetAlias = $this->getAlias($target);
386
387 $qualified = [];
388 foreach ($columns as $alias => $column) {
389 if (is_int($alias) && is_array($column)) {
390 // $columns is $this->requireAndResolveColumns()
391 [$target, $alias, $columnName] = $column;
392 $targetAlias = $this->getAlias($target);
393
394 // Thanks to PHP 5.6 where `list` is evaluated from right to left. It will extract
395 // the values for `$target` and `$alias` then from the third argument (`$column`).
396 $column = $columnName;
397 } elseif ($target === null) {
398 throw new InvalidArgumentException(
399 'Passing no model is only possible if $columns is a generator'
400 );
401 }
402
403 if (is_int($alias)) {
404 if ($column instanceof AliasedExpression) {
405 $alias = $column->getAlias();
406 } elseif ($autoAlias && ! $column instanceof ExpressionInterface) {
407 $alias = $this->qualifyColumnAlias($column, $targetAlias);
408 }
409 } elseif ($target !== $this->query->getModel()) {
410 if (strpos($alias, '.') !== false) {
411 // This is safe, because custom aliases won't be qualified
412 $alias = str_replace('.', '_', $alias);
413 } else {
414 $alias = $this->qualifyColumnAlias($alias, $targetAlias);
415 }
416 }
417
418 if ($column instanceof ResolvedExpression) {
419 $column->setColumns($this->qualifyColumns($column->getResolvedColumns()));
420 } elseif ($column instanceof ExpressionInterface) {
421 $column = clone $column; // The expression may be part of a model and those shouldn't change implicitly
422 $column->setColumns($this->qualifyColumns($column->getColumns(), $target));
423 } else {
424 $column = $this->qualifyColumn($column, $targetAlias);
425 }
426
427 $qualified[$alias] = $column;
428 }
429
430 return $qualified;
431 }
432
433 /**
434 * Qualify the given path by the specified table name
435 *
436 * @param string $path
437 * @param string $tableName
438 *
439 * @return string
440 */
441 public function qualifyPath(string $path, string $tableName): string
442 {
443 $segments = explode('.', $path, 2);
444
445 if ($segments[0] !== $tableName) {
446 array_unshift($segments, $tableName);
447 }
448
449 $path = implode('.', $segments);
450
451 return $path;
452 }
453
454 /**
455 * Get whether the given relation path points to a distinct entity
456 *
457 * @param string $path
458 *
459 * @return bool
460 */
461 public function isDistinctRelation(string $path): bool
462 {
463 foreach ($this->resolveRelations($path) as $relation) {
464 if (! $relation->isOne()) {
465 return false;
466 }
467 }
468
469 return true;
470 }
471
472 /**
473 * Resolve the rightmost relation of the given path
474 *
475 * Also resolves all other relations.
476 *
477 * @param string $path
478 * @param ?Model $subject
479 *
480 * @return Relation
481 */
482 public function resolveRelation(string $path, ?Model $subject = null): Relation
483 {
484 $subject = $subject ?: $this->query->getModel();
485 if (! $this->resolvedRelations->offsetExists($subject) || ! isset($this->resolvedRelations[$subject][$path])) {
486 foreach ($this->resolveRelations($path, $subject) as $_) {
487 // run and exhaust generator
488 }
489 }
490
491 return $this->resolvedRelations[$subject][$path];
492 }
493
494 /**
495 * Resolve all relations of the given path
496 *
497 * Traverses the entire path and yields the path travelled so far as key and the relation as value.
498 *
499 * @param string $path
500 * @param ?Model $subject
501 *
502 * @return Generator
503 * @throws InvalidArgumentException In case $path is not fully qualified
504 * @throws InvalidRelationException In case a relation is unknown
505 */
506 public function resolveRelations(string $path, ?Model $subject = null): Generator
507 {
508 $relations = explode('.', $path);
509 $subject = $subject ?: $this->query->getModel();
510
511 if ($relations[0] !== $subject->getTableAlias()) {
512 throw new InvalidArgumentException(sprintf(
513 'Cannot resolve relation path "%s". Base table alias/name is missing.',
514 $path
515 ));
516 }
517
518 $resolvedRelations = [];
519 if ($this->resolvedRelations->offsetExists($subject)) {
520 $resolvedRelations = $this->resolvedRelations[$subject];
521 }
522
523 $target = $subject;
524 $pathBeingResolved = null;
525 $relation = null;
526 $segments = [array_shift($relations)];
527 while (! empty($relations)) {
528 $newPath = $this->getBehaviors($target)
529 ->rewritePath(join('.', $relations), join('.', $segments));
530 if ($newPath !== null) {
531 $relations = explode('.', $newPath);
532 $pathBeingResolved = $path;
533 }
534
535 $relationName = array_shift($relations);
536 $segments[] = $relationName;
537 $relationPath = join('.', $segments);
538
539 if (isset($resolvedRelations[$relationPath])) {
540 $relation = $resolvedRelations[$relationPath];
541 } else {
542 $targetRelations = $this->getRelations($target);
543 if (! $targetRelations->has($relationName)) {
544 throw new InvalidRelationException($relationName, $target);
545 }
546
547 $relation = $targetRelations->get($relationName);
548 $relation->setSource($target);
549
550 $resolvedRelations[$relationPath] = $relation;
551
552 if ($relation instanceof BelongsToMany) {
553 $this->setAlias($relation->getThrough(), join('_', array_merge(
554 array_slice($segments, 0, -1),
555 [$relation->getThroughAlias()]
556 )));
557 }
558
559 $this->setAlias($relation->getTarget(), join('_', $segments));
560 }
561
562 yield $relationPath => $relation;
563
564 $target = $relation->getTarget();
565 }
566
567 if ($pathBeingResolved !== null) {
568 $resolvedRelations[$pathBeingResolved] = $relation;
569 }
570
571 $this->resolvedRelations->offsetSet($subject, $resolvedRelations);
572 }
573
574 /**
575 * Require and resolve columns
576 *
577 * Related models will be automatically added for eager-loading.
578 *
579 * @param array $columns
580 * @param ?Model $model
581 *
582 * @return Generator
583 *
584 * @throws InvalidColumnException If a column does not exist
585 */
586 public function requireAndResolveColumns(array $columns, ?Model $model = null): Generator
587 {
588 $model = $model ?: $this->query->getModel();
589 $tableName = $model->getTableAlias();
590
591 $baseTableColumns = [];
592 foreach ($columns as $alias => $column) {
593 $columnPath = &$column;
594 if ($column instanceof ExpressionInterface) {
595 $column = new ResolvedExpression(
596 $column,
597 $this->requireAndResolveColumns($column->getColumns(), $model)
598 );
599
600 if (is_int($alias)) {
601 // Scalar queries and such
602 yield [$model, $alias, $column];
603
604 continue;
605 }
606
607 $columnPath = &$alias;
608 } elseif ($column === '*') {
609 yield [$model, $alias, $column];
610
611 continue;
612 }
613
614 $dot = strrpos($columnPath, '.');
615
616 switch (true) {
617 /** @noinspection PhpMissingBreakStatementInspection */
618 case $dot !== false:
619 $relationPath = null;
620 $hydrationPath = substr($columnPath, 0, $dot);
621 $columnPath = substr($columnPath, $dot + 1); // Updates also $column or $alias
622
623 if ($hydrationPath !== $tableName) {
624 $relation = null;
625 $hydrationPath = $this->qualifyPath($hydrationPath, $tableName);
626
627 $relations = new AppendIterator();
628 $relations->append(new ArrayIterator([$tableName => null]));
629 $relations->append($this->resolveRelations($hydrationPath));
630 foreach ($relations as $relationPath => $relation) {
631 if ($column instanceof ExpressionInterface) {
632 continue;
633 }
634
635 if ($relationPath === $tableName) {
636 $subject = $model;
637 } else {
638 /** @var Relation $relation */
639 $subject = $relation->getTarget();
640 }
641
642 $columnName = $columnPath;
643 if ($relationPath !== $hydrationPath) {
644 // It's still an intermediate relation, not the target
645 $columnName = substr($hydrationPath, strlen($relationPath) + 1) . ".$columnName";
646 }
647
648 $newColumn = $this->getBehaviors($subject)->rewriteColumn($columnName, $relationPath);
649 if ($newColumn !== null) {
650 if ($newColumn instanceof ExpressionInterface) {
651 $column = $newColumn;
652 $target = $subject;
653 break 2; // Expressions don't need to be *withed* and get no automatic alias either
654 }
655
656 $column = $newColumn;
657 break;
658 }
659 }
660
661 if (is_int($alias) && $relationPath !== $hydrationPath) {
662 // If the actual relation is resolved differently,
663 // ensure the hydration path is not an unexpected one
664 $alias = "$hydrationPath.$column";
665 }
666
667 $this->query->with($hydrationPath);
668 $target = $relation->getTarget();
669
670 break;
671 }
672 // Move to default
673 default:
674 $relationPath = null;
675 $hydrationPath = null;
676 $target = $model;
677
678 if (! $column instanceof ExpressionInterface) {
679 $column = $this->getBehaviors($target)->rewriteColumn($column) ?: $column;
680 }
681
682 if (is_int($alias) && ! $column instanceof AliasedExpression) {
683 if (! isset($baseTableColumns[$columnPath])) {
684 $baseTableColumns[$columnPath] = true;
685 } else {
686 // Don't yield base table columns multiple times.
687 // Duplicate columns without an alias may lead to SQL errors
688 continue 2;
689 }
690 }
691 }
692
693 if (! $column instanceof ExpressionInterface) {
694 $targetColumns = $target->getColumns();
695 if (isset($targetColumns[$column])) {
696 // $column is actually an alias
697 $alias = is_string($alias) ? $alias : ($relationPath ? "$hydrationPath.$column" : $column);
698 $column = $targetColumns[$column];
699
700 if ($column instanceof ExpressionInterface) {
701 $qualifier = $relationPath ? "$hydrationPath." : '';
702
703 $column = new ResolvedExpression(
704 $column,
705 $this->requireAndResolveColumns(array_map(function ($c) use ($qualifier) {
706 return $qualifier . $c;
707 }, $column->getColumns()), $model)
708 );
709 }
710 }
711 }
712
713 if (! $column instanceof ExpressionInterface && ! $this->hasSelectableColumn($target, $columnPath)) {
714 throw new InvalidColumnException($columnPath, $target);
715 }
716
717 yield [$target, $alias, $column];
718 }
719 }
720
721 /**
722 * Collect all selectable columns from the given model
723 *
724 * @param Model $subject
725 *
726 * @return void
727 */
728 protected function collectColumns(Model $subject): void
729 {
730 // Don't fail if Model::getColumns() also contains the primary key columns
731 $columns = array_merge((array) $subject->getKeyName(), (array) $subject->getColumns());
732
733 $this->selectColumns->offsetSet($subject, $columns);
734
735 $selectable = [];
736
737 foreach ($columns as $alias => $column) {
738 if (is_string($alias)) {
739 $selectable[$alias] = true;
740 }
741
742 if (is_string($column)) {
743 $selectable[$column] = true;
744 }
745 }
746
747 $this->selectableColumns->offsetSet($subject, $selectable);
748 }
749
750 /**
751 * Collect all meta data from the given model and its direct relations
752 *
753 * @param Model $subject
754 *
755 * @return array
756 *
757 * @throws LogicException If a column definition's name differs from its array index
758 */
759 protected function collectMetaData(Model $subject): array
760 {
761 $definitions = [];
762 foreach ($subject->getColumnDefinitions() as $name => $data) {
763 if ($data instanceof ColumnDefinition) {
764 $definition = $data;
765 } else {
766 if (is_string($data)) {
767 $data = ['name' => $name, 'label' => $data];
768 } elseif (! isset($data[$name])) {
769 $data['name'] = $name;
770 }
771
772 $definition = ColumnDefinition::fromArray($data);
773 }
774
775 if (is_string($name) && $definition->getName() !== $name) {
776 throw new LogicException(sprintf(
777 'Model %s provides a column definition with a different name (%s) than the index (%s)',
778 get_class($subject),
779 $definition->getName(),
780 $name
781 ));
782 }
783
784 $definitions[$name] = $definition;
785 }
786
787 return $definitions;
788 }
789 }