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