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