Debian Codegraph @

vendor/doctrine/collections/src/Criteria.php

raw
1 <?php
2
3 declare(strict_types=1);
4
5 namespace Doctrine\Common\Collections;
6
7 use Doctrine\Common\Collections\Expr\CompositeExpression;
8 use Doctrine\Common\Collections\Expr\Expression;
9 use Doctrine\Deprecations\Deprecation;
10
11 use function array_map;
12 use function func_get_arg;
13 use function func_num_args;
14 use function strtoupper;
15
16 /**
17 * Criteria for filtering Selectable collections.
18 *
19 * @phpstan-consistent-constructor
20 * @final since 2.5
21 */
22 class Criteria
23 {
24 /** @deprecated use Order::Ascending instead */
25 final public const ASC = 'ASC';
26
27 /** @deprecated use Order::Descending instead */
28 final public const DESC = 'DESC';
29
30 private static ExpressionBuilder|null $expressionBuilder = null;
31
32 /** @var array<string, Order> */
33 private array $orderings = [];
34
35 private int|null $firstResult = null;
36 private int|null $maxResults = null;
37
38 /**
39 * Creates an instance of the class.
40 *
41 * @return static
42 */
43 public static function create(/* bool $accessRawFieldValues = false */): self
44 {
45 $accessRawFieldValues = 0 < func_num_args() ? func_get_arg(0) : false;
46
47 return new static(firstResult: 0, accessRawFieldValues: $accessRawFieldValues);
48 }
49
50 /**
51 * Returns the expression builder.
52 *
53 * @return ExpressionBuilder
54 */
55 public static function expr()
56 {
57 if (self::$expressionBuilder === null) {
58 self::$expressionBuilder = new ExpressionBuilder();
59 }
60
61 return self::$expressionBuilder;
62 }
63
64 /**
65 * Construct a new Criteria.
66 *
67 * @param int|null $firstResult
68 * @param array<string, string|Order>|null $orderings
69 */
70 public function __construct(
71 private Expression|null $expression = null,
72 array|null $orderings = null,
73 int|Placeholder|null $firstResult = Placeholder::NotSpecified,
74 int|null $maxResults = null,
75 private bool $accessRawFieldValues = false,
76 ) {
77 if (! $accessRawFieldValues) {
78 Deprecation::trigger(
79 'doctrine/collections',
80 'https://github.com/doctrine/collections/pull/472',
81 'Not enabling raw field value access for the Criteria matching API in %s is deprecated. Raw field access will be the only supported method in 3.0',
82 self::class,
83 );
84 }
85
86 if ($firstResult === null) {
87 Deprecation::trigger(
88 'doctrine/collections',
89 'https://github.com/doctrine/collections/pull/311',
90 'Passing null as $firstResult to the constructor of %s is deprecated. Pass 0 instead or omit the argument.',
91 self::class,
92 );
93 }
94
95 if ($firstResult === Placeholder::NotSpecified) {
96 $firstResult = null;
97 }
98
99 $this->setFirstResult($firstResult);
100 $this->setMaxResults($maxResults);
101
102 if ($orderings === null) {
103 return;
104 }
105
106 $this->orderBy($orderings);
107 }
108
109 /**
110 * Sets the where expression to evaluate when this Criteria is searched for.
111 *
112 * @return $this
113 */
114 public function where(Expression $expression)
115 {
116 $this->expression = $expression;
117
118 return $this;
119 }
120
121 /**
122 * Appends the where expression to evaluate when this Criteria is searched for
123 * using an AND with previous expression.
124 *
125 * @return $this
126 */
127 public function andWhere(Expression $expression)
128 {
129 if ($this->expression === null) {
130 return $this->where($expression);
131 }
132
133 $this->expression = new CompositeExpression(
134 CompositeExpression::TYPE_AND,
135 [$this->expression, $expression],
136 );
137
138 return $this;
139 }
140
141 /**
142 * Appends the where expression to evaluate when this Criteria is searched for
143 * using an OR with previous expression.
144 *
145 * @return $this
146 */
147 public function orWhere(Expression $expression)
148 {
149 if ($this->expression === null) {
150 return $this->where($expression);
151 }
152
153 $this->expression = new CompositeExpression(
154 CompositeExpression::TYPE_OR,
155 [$this->expression, $expression],
156 );
157
158 return $this;
159 }
160
161 /**
162 * Gets the expression attached to this Criteria.
163 *
164 * @return Expression|null
165 */
166 public function getWhereExpression()
167 {
168 return $this->expression;
169 }
170
171 /**
172 * Gets the current orderings of this Criteria.
173 *
174 * @deprecated use orderings() instead
175 *
176 * @return array<string, string>
177 */
178 public function getOrderings()
179 {
180 Deprecation::trigger(
181 'doctrine/collections',
182 'https://github.com/doctrine/collections/pull/389',
183 'Calling %s() is deprecated. Use %s::orderings() instead.',
184 __METHOD__,
185 self::class,
186 );
187
188 return array_map(
189 static fn (Order $ordering): string => $ordering->value,
190 $this->orderings,
191 );
192 }
193
194 /**
195 * Gets the current orderings of this Criteria.
196 *
197 * @return array<string, Order>
198 */
199 public function orderings(): array
200 {
201 return $this->orderings;
202 }
203
204 /**
205 * Sets the ordering of the result of this Criteria.
206 *
207 * Keys are field and values are the order, being a valid Order enum case.
208 *
209 * @see Order::Ascending
210 * @see Order::Descending
211 *
212 * @param array<string, string|Order> $orderings
213 *
214 * @return $this
215 */
216 public function orderBy(array $orderings)
217 {
218 $method = __METHOD__;
219 $this->orderings = array_map(
220 static function (string|Order $ordering) use ($method): Order {
221 if ($ordering instanceof Order) {
222 return $ordering;
223 }
224
225 static $triggered = false;
226
227 if (! $triggered) {
228 Deprecation::trigger(
229 'doctrine/collections',
230 'https://github.com/doctrine/collections/pull/389',
231 'Passing non-Order enum values to %s() is deprecated. Pass Order enum values instead.',
232 $method,
233 );
234 }
235
236 $triggered = true;
237
238 return strtoupper($ordering) === Order::Ascending->value ? Order::Ascending : Order::Descending;
239 },
240 $orderings,
241 );
242
243 return $this;
244 }
245
246 /**
247 * Gets the current first result option of this Criteria.
248 *
249 * @return int|null
250 */
251 public function getFirstResult()
252 {
253 return $this->firstResult;
254 }
255
256 /**
257 * Set the number of first result that this Criteria should return.
258 *
259 * @param int|null $firstResult The value to set.
260 *
261 * @return $this
262 */
263 public function setFirstResult(int|null $firstResult)
264 {
265 if ($firstResult === null) {
266 Deprecation::triggerIfCalledFromOutside(
267 'doctrine/collections',
268 'https://github.com/doctrine/collections/pull/311',
269 'Passing null to %s() is deprecated, pass 0 instead.',
270 __METHOD__,
271 );
272 }
273
274 $this->firstResult = $firstResult;
275
276 return $this;
277 }
278
279 /**
280 * Gets maxResults.
281 *
282 * @return int|null
283 */
284 public function getMaxResults()
285 {
286 return $this->maxResults;
287 }
288
289 /**
290 * Sets maxResults.
291 *
292 * @param int|null $maxResults The value to set.
293 *
294 * @return $this
295 */
296 public function setMaxResults(int|null $maxResults)
297 {
298 $this->maxResults = $maxResults;
299
300 return $this;
301 }
302
303 /** @internal */
304 public function isRawFieldValueAccessEnabled(): bool
305 {
306 return $this->accessRawFieldValues;
307 }
308 }