[CLEANUP] The correct case must be used for standard PHP types in phpdoc
[Packages/TYPO3.CMS.git] / typo3 / sysext / extbase / Classes / Persistence / QueryInterface.php
1 <?php
2 namespace TYPO3\CMS\Extbase\Persistence;
3
4 /*
5 * This file is part of the TYPO3 CMS project.
6 *
7 * It is free software; you can redistribute it and/or modify it under
8 * the terms of the GNU General Public License, either version 2
9 * of the License, or any later version.
10 *
11 * For the full copyright and license information, please read the
12 * LICENSE.txt file that was distributed with this source code.
13 *
14 * The TYPO3 project - inspiring people to share!
15 */
16
17 use TYPO3\CMS\Extbase\Persistence\Generic\Qom\AndInterface;
18 use TYPO3\CMS\Extbase\Persistence\Generic\Qom\ComparisonInterface;
19 use TYPO3\CMS\Extbase\Persistence\Generic\Qom\ConstraintInterface;
20 use TYPO3\CMS\Extbase\Persistence\Generic\Qom\OrInterface;
21
22 /**
23 * A persistence query interface
24 *
25 * @api
26 */
27 interface QueryInterface
28 {
29 /**
30 * The '=' comparison operator.
31 *
32 * @api
33 */
34 const OPERATOR_EQUAL_TO = 1;
35
36 /**
37 * For NULL we have to use 'IS' instead of '='
38 *
39 * @api
40 */
41 const OPERATOR_EQUAL_TO_NULL = 101;
42
43 /**
44 * The '!=' comparison operator.
45 *
46 * @api
47 */
48 const OPERATOR_NOT_EQUAL_TO = 2;
49
50 /**
51 * For NULL we have to use 'IS NOT' instead of '!='
52 *
53 * @api
54 */
55 const OPERATOR_NOT_EQUAL_TO_NULL = 202;
56
57 /**
58 * The '<' comparison operator.
59 *
60 * @api
61 */
62 const OPERATOR_LESS_THAN = 3;
63
64 /**
65 * The '<=' comparison operator.
66 *
67 * @api
68 */
69 const OPERATOR_LESS_THAN_OR_EQUAL_TO = 4;
70
71 /**
72 * The '>' comparison operator.
73 *
74 * @api
75 */
76 const OPERATOR_GREATER_THAN = 5;
77
78 /**
79 * The '>=' comparison operator.
80 *
81 * @api
82 */
83 const OPERATOR_GREATER_THAN_OR_EQUAL_TO = 6;
84
85 /**
86 * The 'like' comparison operator.
87 *
88 * @api
89 */
90 const OPERATOR_LIKE = 7;
91
92 /**
93 * The 'contains' comparison operator for collections.
94 *
95 * @api
96 */
97 const OPERATOR_CONTAINS = 8;
98
99 /**
100 * The 'in' comparison operator.
101 *
102 * @api
103 */
104 const OPERATOR_IN = 9;
105
106 /**
107 * The 'is NULL' comparison operator.
108 *
109 * @api
110 */
111 const OPERATOR_IS_NULL = 10;
112
113 /**
114 * The 'is empty' comparison operator for collections.
115 *
116 * @api
117 */
118 const OPERATOR_IS_EMPTY = 11;
119
120 /**
121 * Constants representing the direction when ordering result sets.
122 */
123 const ORDER_ASCENDING = 'ASC';
124 const ORDER_DESCENDING = 'DESC';
125
126 /**
127 * Gets the node-tuple source for this query.
128 *
129 * @return \TYPO3\CMS\Extbase\Persistence\Generic\Qom\SourceInterface the node-tuple source; non-NULL
130 * @deprecated since Extbase 6.0, will be removed in Extbase 7.0. It is deprecated only in the interface to be more
131 * in sync with Flow in future and will stay in Generic Persistence.
132 */
133 public function getSource();
134
135 /**
136 * Executes the query and returns the result.
137 *
138 * @param bool $returnRawQueryResult avoids the object mapping by the persistence
139 * @return \TYPO3\CMS\Extbase\Persistence\QueryResultInterface|array The query result object or an array if $returnRawQueryResult is TRUE
140 * @api
141 */
142 public function execute($returnRawQueryResult = false);
143
144 /**
145 * Sets the property names to order the result by. Expected like this:
146 * array(
147 * 'foo' => \TYPO3\CMS\Extbase\Persistence\QueryInterface::ORDER_ASCENDING,
148 * 'bar' => \TYPO3\CMS\Extbase\Persistence\QueryInterface::ORDER_DESCENDING
149 * )
150 *
151 * @param array $orderings The property names to order by
152 * @return \TYPO3\CMS\Extbase\Persistence\QueryInterface
153 * @api
154 */
155 public function setOrderings(array $orderings);
156
157 /**
158 * Sets the maximum size of the result set to limit. Returns $this to allow
159 * for chaining (fluid interface).
160 *
161 * @param int $limit
162 * @return \TYPO3\CMS\Extbase\Persistence\QueryInterface
163 * @api
164 */
165 public function setLimit($limit);
166
167 /**
168 * Sets the start offset of the result set to offset. Returns $this to
169 * allow for chaining (fluid interface).
170 *
171 * @param int $offset
172 * @return \TYPO3\CMS\Extbase\Persistence\QueryInterface
173 * @api
174 */
175 public function setOffset($offset);
176
177 /**
178 * The constraint used to limit the result set. Returns $this to allow
179 * for chaining (fluid interface).
180 *
181 * @param ConstraintInterface $constraint Some constraint, depending on the backend
182 * @return \TYPO3\CMS\Extbase\Persistence\QueryInterface
183 * @api
184 */
185 public function matching($constraint);
186
187 /**
188 * Performs a logical conjunction of the two given constraints. The method
189 * takes one or more constraints and concatenates them with a boolean AND.
190 * It also accepts a single array of constraints to be concatenated.
191 *
192 * @param mixed $constraint1 The first of multiple constraints or an array of constraints.
193 * @return AndInterface
194 * @api
195 */
196 public function logicalAnd($constraint1);
197
198 /**
199 * Performs a logical disjunction of the two given constraints. The method
200 * takes one or more constraints and concatenates them with a boolean OR.
201 * It also accepts a single array of constraints to be concatenated.
202 *
203 * @param mixed $constraint1 The first of multiple constraints or an array of constraints.
204 * @return OrInterface
205 * @api
206 */
207 public function logicalOr($constraint1);
208
209 /**
210 * Performs a logical negation of the given constraint
211 *
212 * @param ConstraintInterface $constraint Constraint to negate
213 * @return \TYPO3\CMS\Extbase\Persistence\Generic\Qom\NotInterface
214 * @api
215 */
216 public function logicalNot(ConstraintInterface $constraint);
217
218 /**
219 * Returns an equals criterion used for matching objects against a query.
220 *
221 * It matches if the $operand equals the value of the property named
222 * $propertyName. If $operand is NULL a strict check for NULL is done. For
223 * strings the comparison can be done with or without case-sensitivity.
224 *
225 * @param string $propertyName The name of the property to compare against
226 * @param mixed $operand The value to compare with
227 * @param bool $caseSensitive Whether the equality test should be done case-sensitive for strings
228 * @return \TYPO3\CMS\Extbase\Persistence\Generic\Qom\ComparisonInterface
229 * @api
230 */
231 public function equals($propertyName, $operand, $caseSensitive = true);
232
233 /**
234 * Returns a like criterion used for matching objects against a query.
235 * Matches if the property named $propertyName is like the $operand, using
236 * standard SQL wildcards.
237 *
238 * @param string $propertyName The name of the property to compare against
239 * @param string $operand The value to compare with
240 * @param bool $caseSensitive Whether the matching should be done case-sensitive
241 * @return ComparisonInterface
242 * @throws \TYPO3\CMS\Extbase\Persistence\Exception\InvalidQueryException if used on a non-string property
243 * @api
244 */
245 public function like($propertyName, $operand, $caseSensitive = true);
246
247 /**
248 * Returns a "contains" criterion used for matching objects against a query.
249 * It matches if the multivalued property contains the given operand.
250 *
251 * If NULL is given as $operand, there will never be a match!
252 *
253 * @param string $propertyName The name of the multivalued property to compare against
254 * @param mixed $operand The value to compare with
255 * @return ComparisonInterface
256 * @throws \TYPO3\CMS\Extbase\Persistence\Exception\InvalidQueryException if used on a single-valued property
257 * @api
258 */
259 public function contains($propertyName, $operand);
260
261 /**
262 * Returns an "in" criterion used for matching objects against a query. It
263 * matches if the property's value is contained in the multivalued operand.
264 *
265 * @param string $propertyName The name of the property to compare against
266 * @param mixed $operand The value to compare with, multivalued
267 * @return ComparisonInterface
268 * @throws \TYPO3\CMS\Extbase\Persistence\Exception\InvalidQueryException if used on a multi-valued property
269 * @api
270 */
271 public function in($propertyName, $operand);
272
273 /**
274 * Returns a less than criterion used for matching objects against a query
275 *
276 * @param string $propertyName The name of the property to compare against
277 * @param mixed $operand The value to compare with
278 * @return ComparisonInterface
279 * @throws \TYPO3\CMS\Extbase\Persistence\Exception\InvalidQueryException if used on a multi-valued property or with a non-literal/non-DateTime operand
280 * @api
281 */
282 public function lessThan($propertyName, $operand);
283
284 /**
285 * Returns a less or equal than criterion used for matching objects against a query
286 *
287 * @param string $propertyName The name of the property to compare against
288 * @param mixed $operand The value to compare with
289 * @return ComparisonInterface
290 * @throws \TYPO3\CMS\Extbase\Persistence\Exception\InvalidQueryException if used on a multi-valued property or with a non-literal/non-DateTime operand
291 * @api
292 */
293 public function lessThanOrEqual($propertyName, $operand);
294
295 /**
296 * Returns a greater than criterion used for matching objects against a query
297 *
298 * @param string $propertyName The name of the property to compare against
299 * @param mixed $operand The value to compare with
300 * @return ComparisonInterface
301 * @throws \TYPO3\CMS\Extbase\Persistence\Exception\InvalidQueryException if used on a multi-valued property or with a non-literal/non-DateTime operand
302 * @api
303 */
304 public function greaterThan($propertyName, $operand);
305
306 /**
307 * Returns a greater than or equal criterion used for matching objects against a query
308 *
309 * @param string $propertyName The name of the property to compare against
310 * @param mixed $operand The value to compare with
311 * @return ComparisonInterface
312 * @throws \TYPO3\CMS\Extbase\Persistence\Exception\InvalidQueryException if used on a multi-valued property or with a non-literal/non-DateTime operand
313 * @api
314 */
315 public function greaterThanOrEqual($propertyName, $operand);
316
317 /**
318 * Returns the type this query cares for.
319 *
320 * @return string
321 * @api
322 */
323 public function getType();
324
325 /**
326 * Sets the Query Settings. These Query settings must match the settings expected by
327 * the specific Storage Backend.
328 *
329 * @param \TYPO3\CMS\Extbase\Persistence\Generic\QuerySettingsInterface $querySettings The Query Settings
330 * @todo decide whether this can be deprecated somewhen
331 * @api This method is not part of TYPO3Flow API
332 */
333 public function setQuerySettings(Generic\QuerySettingsInterface $querySettings);
334
335 /**
336 * Returns the Query Settings.
337 *
338 * @return \TYPO3\CMS\Extbase\Persistence\Generic\QuerySettingsInterface $querySettings The Query Settings
339 * @todo decide whether this can be deprecated eventually
340 * @api This method is not part of TYPO3Flow API
341 */
342 public function getQuerySettings();
343
344 /**
345 * Returns the query result count.
346 *
347 * @return int The query result count
348 * @api
349 */
350 public function count();
351
352 /**
353 * Gets the property names to order the result by, like this:
354 * array(
355 * 'foo' => \TYPO3\CMS\Extbase\Persistence\QueryInterface::ORDER_ASCENDING,
356 * 'bar' => \TYPO3\CMS\Extbase\Persistence\QueryInterface::ORDER_DESCENDING
357 * )
358 *
359 * @return array
360 * @api
361 */
362 public function getOrderings();
363
364 /**
365 * Returns the maximum size of the result set to limit.
366 *
367 * @return int
368 * @api
369 */
370 public function getLimit();
371
372 /**
373 * Returns the start offset of the result set.
374 *
375 * @return int
376 * @api
377 */
378 public function getOffset();
379
380 /**
381 * Gets the constraint for this query.
382 *
383 * @return ConstraintInterface|null the constraint, or null if none
384 * @api
385 */
386 public function getConstraint();
387
388 /**
389 * Returns an "isEmpty" criterion used for matching objects against a query.
390 * It matches if the multivalued property contains no values or is NULL.
391 *
392 * @param string $propertyName The name of the multivalued property to compare against
393 * @return bool
394 * @throws \TYPO3\CMS\Extbase\Persistence\Exception\InvalidQueryException if used on a single-valued property
395 * @api
396 */
397 public function isEmpty($propertyName);
398
399 /**
400 * Sets the source to fetch the result from
401 *
402 * @param \TYPO3\CMS\Extbase\Persistence\Generic\Qom\SourceInterface $source
403 */
404 public function setSource(Generic\Qom\SourceInterface $source);
405
406 /**
407 * Returns the statement of this query.
408 *
409 * @return \TYPO3\CMS\Extbase\Persistence\Generic\Qom\Statement
410 */
411 public function getStatement();
412 }