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