Debian Codegraph @

vendor/ipl/orm/src/Relation.php

raw
1 <?php
2
3 namespace ipl\Orm;
4
5 use Generator;
6 use UnexpectedValueException;
7
8 /**
9 * Relations represent the connection between models, i.e. the association between rows in one or more tables
10 * on the basis of matching key columns. The relationships are defined using candidate key-foreign key constructs.
11 */
12 class Relation
13 {
14 /** @var string Name of the relation */
15 protected $name;
16
17 /** @var Model Source model */
18 protected $source;
19
20 /** @var string|array|null Column name(s) of the foreign key found in the target table */
21 protected string|array|null $foreignKey = null;
22
23 /** @var string|array|null Column name(s) of the candidate key in the source table which references the foreign key */
24 protected string|array|null $candidateKey = null;
25
26 /** @var string Target model class */
27 protected $targetClass;
28
29 /** @var Model Target model */
30 protected $target;
31
32 /** @var string Type of the JOIN used in the query */
33 protected string $joinType = 'INNER';
34
35 /** @var bool Whether this is the inverse of a relationship */
36 protected bool $inverse = false;
37
38 /** @var bool Whether this is a to-one relationship */
39 protected bool $isOne = true;
40
41 /**
42 * Get the default column name(s) in the source table used to match the foreign key
43 *
44 * The default candidate key is the primary key column name(s) of the given model.
45 *
46 * @param Model $source
47 *
48 * @return array
49 */
50 public static function getDefaultCandidateKey(Model $source): array
51 {
52 return (array) $source->getKeyName();
53 }
54
55 /**
56 * Get the default column name(s) of the foreign key found in the target table
57 *
58 * The default foreign key is the given model's primary key column name(s) prefixed with its table name.
59 *
60 * @param Model $source
61 *
62 * @return array
63 */
64 public static function getDefaultForeignKey(Model $source): array
65 {
66 $tableName = $source->getTableName();
67
68 return array_map(
69 function ($key) use ($tableName) {
70 return "{$tableName}_{$key}";
71 },
72 (array) $source->getKeyName()
73 );
74 }
75
76 /**
77 * Get whether this is a to-one relationship
78 *
79 * @return bool
80 */
81 public function isOne(): bool
82 {
83 return $this->isOne;
84 }
85
86 /**
87 * Get the name of the relation
88 *
89 * @return string
90 */
91 public function getName()
92 {
93 return $this->name;
94 }
95
96 /**
97 * Set the name of the relation
98 *
99 * @param string $name
100 *
101 * @return $this
102 */
103 public function setName(string $name): static
104 {
105 $this->name = $name;
106
107 return $this;
108 }
109
110 /**
111 * Get the source model of the relation
112 *
113 * @return Model
114 */
115 public function getSource()
116 {
117 return $this->source;
118 }
119
120 /**
121 * Set the source model of the relation
122 *
123 * @param Model $source
124 *
125 * @return $this
126 */
127 public function setSource(Model $source): static
128 {
129 $this->source = $source;
130
131 return $this;
132 }
133
134 /**
135 * Get the column name(s) of the foreign key found in the target table
136 *
137 * @return string|array|null Array if the foreign key is compound, string otherwise
138 */
139 public function getForeignKey(): string|array|null
140 {
141 return $this->foreignKey;
142 }
143
144 /**
145 * Set the column name(s) of the foreign key found in the target table
146 *
147 * @param string|array|null $foreignKey Array if the foreign key is compound, string otherwise
148 *
149 * @return $this
150 */
151 public function setForeignKey(string|array|null $foreignKey): static
152 {
153 $this->foreignKey = $foreignKey;
154
155 return $this;
156 }
157
158 /**
159 * Get the column name(s) of the candidate key in the source table which references the foreign key
160 *
161 * @return string|array|null Array if the candidate key is compound, string otherwise
162 */
163 public function getCandidateKey(): string|array|null
164 {
165 return $this->candidateKey;
166 }
167
168 /**
169 * Set the column name(s) of the candidate key in the source table which references the foreign key
170 *
171 * @param string|array|null $candidateKey Array if the candidate key is compound, string otherwise
172 *
173 * @return $this
174 */
175 public function setCandidateKey(string|array|null $candidateKey): static
176 {
177 $this->candidateKey = $candidateKey;
178
179 return $this;
180 }
181
182 /**
183 * Get the target model class
184 *
185 * @return string
186 */
187 public function getTargetClass()
188 {
189 return $this->targetClass;
190 }
191
192 /**
193 * Set the target model class
194 *
195 * @param string $targetClass
196 *
197 * @return $this
198 */
199 public function setTargetClass(string $targetClass): static
200 {
201 $this->targetClass = $targetClass;
202
203 return $this;
204 }
205
206 /**
207 * Get the target model
208 *
209 * Returns the model from {@link setTarget()} or an instance of {@link getTargetClass()}.
210 * Note that multiple calls to this method always returns the very same model instance.
211 *
212 * @return Model
213 */
214 public function getTarget()
215 {
216 if ($this->target === null) {
217 $targetClass = $this->getTargetClass();
218 $this->target = new $targetClass();
219 }
220
221 return $this->target;
222 }
223
224 /**
225 * Set the the target model
226 *
227 * @param Model $target
228 *
229 * @return $this
230 */
231 public function setTarget(Model $target): static
232 {
233 $this->target = $target;
234
235 return $this;
236 }
237
238 /**
239 * Get the type of the JOIN used in the query
240 *
241 * @return string
242 */
243 public function getJoinType(): string
244 {
245 return $this->joinType;
246 }
247
248 /**
249 * Set the type of the JOIN used in the query
250 *
251 * @param string $joinType
252 *
253 * @return Relation
254 */
255 public function setJoinType(string $joinType): static
256 {
257 $this->joinType = $joinType;
258
259 return $this;
260 }
261
262 /**
263 * Determine the candidate key-foreign key construct of the relation
264 *
265 * @param Model $source
266 *
267 * @return array Candidate key-foreign key column name pairs
268 *
269 * @throws UnexpectedValueException If there's no candidate key to be found
270 * or the foreign key count does not match the candidate key count
271 */
272 public function determineKeys(Model $source): array
273 {
274 $candidateKey = (array) $this->getCandidateKey();
275
276 if (empty($candidateKey)) {
277 $candidateKey = $this->inverse
278 ? static::getDefaultForeignKey($this->getTarget())
279 : static::getDefaultCandidateKey($source);
280 }
281
282 if (empty($candidateKey)) {
283 throw new UnexpectedValueException(sprintf(
284 "Can't join relation '%s' in model '%s'. No candidate key found.",
285 $this->getName(),
286 get_class($source)
287 ));
288 }
289
290 $foreignKey = (array) $this->getForeignKey();
291
292 if (empty($foreignKey)) {
293 $foreignKey = $this->inverse
294 ? static::getDefaultCandidateKey($this->getTarget())
295 : static::getDefaultForeignKey($source);
296 }
297
298 if (count($foreignKey) !== count($candidateKey)) {
299 throw new UnexpectedValueException(sprintf(
300 "Can't join relation '%s' in model '%s'."
301 . " Foreign key count (%s) does not match candidate key count (%s).",
302 $this->getName(),
303 get_class($source),
304 implode(', ', $foreignKey),
305 implode(', ', $candidateKey)
306 ));
307 }
308
309 return array_combine($foreignKey, $candidateKey);
310 }
311
312 /**
313 * Resolve the relation
314 *
315 * Yields a three-element array consisting of the source model, target model and the join keys.
316 *
317 * @return Generator
318 */
319 public function resolve(): Generator
320 {
321 $source = $this->getSource();
322
323 yield [$source, $this->getTarget(), $this->determineKeys($source)];
324 }
325 }