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