Debian Codegraph @

vendor/ipl/orm/src/Relations.php

raw
1 <?php
2
3 namespace ipl\Orm;
4
5 use ArrayIterator;
6 use InvalidArgumentException;
7 use ipl\Orm\Exception\InvalidRelationException;
8 use ipl\Orm\Relation\BelongsTo;
9 use ipl\Orm\Relation\BelongsToMany;
10 use ipl\Orm\Relation\BelongsToOne;
11 use ipl\Orm\Relation\HasMany;
12 use ipl\Orm\Relation\HasOne;
13 use IteratorAggregate;
14 use Traversable;
15
16 use function ipl\Stdlib\get_php_type;
17
18 /**
19 * Collection of a model's relations.
20 */
21 class Relations implements IteratorAggregate
22 {
23 /** @var Relation[] */
24 protected array $relations = [];
25
26 /**
27 * Get whether a relation with the given name exists
28 *
29 * @param string $name
30 *
31 * @return bool
32 */
33 public function has(string $name): bool
34 {
35 return isset($this->relations[$name]);
36 }
37
38 /**
39 * Get the relation with the given name
40 *
41 * @param string $name
42 *
43 * @return Relation
44 *
45 * @throws InvalidArgumentException If the relation with the given name does not exist
46 */
47 public function get(string $name): Relation
48 {
49 $this->assertRelationExists($name);
50
51 return $this->relations[$name];
52 }
53
54 /**
55 * Add the given relation to the collection
56 *
57 * @param Relation $relation
58 *
59 * @return $this
60 *
61 * @throws InvalidArgumentException If a relation with the given name already exists
62 */
63 public function add(Relation $relation): static
64 {
65 $name = $relation->getName();
66
67 $this->assertRelationDoesNotYetExist($name);
68
69 $this->relations[$name] = $relation;
70
71 return $this;
72 }
73
74 /**
75 * Create a new relation from the given class, name and target model class
76 *
77 * @param string $class Class of the relation to create
78 * @param string $name Name of the relation
79 * @param string $targetClass Target model class
80 *
81 * @return BelongsTo|BelongsToOne|BelongsToMany|HasMany|HasOne|Relation
82 *
83 * @throws InvalidArgumentException If the target model class is not of type string
84 */
85 public function create(string $class, string $name, string $targetClass): Relation
86 {
87 $relation = new $class();
88
89 if (! $relation instanceof Relation) {
90 throw new InvalidArgumentException(sprintf(
91 '%s() expects parameter 1 to be a subclass of %s, %s given',
92 __METHOD__,
93 Relation::class,
94 get_php_type($relation)
95 ));
96 }
97
98 // Test target model
99 $target = new $targetClass();
100 if (! $target instanceof Model) {
101 throw new InvalidArgumentException(sprintf(
102 '%s() expects parameter 3 to be a subclass of %s, %s given',
103 __METHOD__,
104 Model::class,
105 get_php_type($target)
106 ));
107 }
108
109 /** @var Relation $relation */
110 $relation
111 ->setName($name)
112 ->setTarget($target)
113 ->setTargetClass($targetClass);
114
115 return $relation;
116 }
117
118 /**
119 * Define a one-to-one relationship
120 *
121 * @param string $name Name of the relation
122 * @param string $targetClass Target model class
123 *
124 * @return HasOne
125 */
126 public function hasOne(string $name, string $targetClass): HasOne
127 {
128 /** @var HasOne $relation */
129 $relation = $this->create(HasOne::class, $name, $targetClass);
130
131 $this->add($relation);
132
133 return $relation;
134 }
135
136 /**
137 * Define a one-to-many relationship
138 *
139 * @param string $name Name of the relation
140 * @param string $targetClass Target model class
141 *
142 * @return HasMany
143 */
144 public function hasMany(string $name, string $targetClass): HasMany
145 {
146 /** @var HasMany $relation */
147 $relation = $this->create(HasMany::class, $name, $targetClass);
148
149 $this->add($relation);
150
151 return $relation;
152 }
153
154 /**
155 * Define the inverse of a one-to-one or one-to-many relationship
156 *
157 * @param string $name Name of the relation
158 * @param string $targetClass Target model class
159 *
160 * @return BelongsTo
161 */
162 public function belongsTo(string $name, string $targetClass): BelongsTo
163 {
164 /** @var BelongsTo $relation */
165 $relation = $this->create(BelongsTo::class, $name, $targetClass);
166
167 $this->add($relation);
168
169 return $relation;
170 }
171
172 /**
173 * Define a one-to-one relationship with a junction table
174 *
175 * @param string $name Name of the relation
176 * @param string $targetClass Target model class
177 *
178 * @return BelongsToOne
179 */
180 public function belongsToOne(string $name, string $targetClass): BelongsToOne
181 {
182 /** @var BelongsToOne $relation */
183 $relation = $this->create(BelongsToOne::class, $name, $targetClass);
184
185 $this->add($relation);
186
187 return $relation;
188 }
189
190 /**
191 * Define a many-to-many relationship
192 *
193 * @param string $name Name of the relation
194 * @param string $targetClass Target model class
195 *
196 * @return BelongsToMany
197 */
198 public function belongsToMany(string $name, string $targetClass): BelongsToMany
199 {
200 /** @var BelongsToMany $relation */
201 $relation = $this->create(BelongsToMany::class, $name, $targetClass);
202
203 $this->add($relation);
204
205 return $relation;
206 }
207
208 public function getIterator(): Traversable
209 {
210 return new ArrayIterator($this->relations);
211 }
212
213 /**
214 * Throw exception if a relation with the given name already exists
215 *
216 * @param string $name
217 *
218 * @return void
219 *
220 * @throws InvalidArgumentException
221 */
222 protected function assertRelationDoesNotYetExist(string $name): void
223 {
224 if ($this->has($name)) {
225 throw new InvalidArgumentException("Relation '$name' already exists");
226 }
227 }
228
229 /**
230 * Throw exception if a relation with the given name does not exist
231 *
232 * @param string $name
233 *
234 * @throws InvalidArgumentException
235 */
236 protected function assertRelationExists(string $name): void
237 {
238 if (! $this->has($name)) {
239 throw new InvalidRelationException($name);
240 }
241 }
242 }