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