www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Entity/Query/QueryInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Entity\Query;
   4
   5 use Drupal\Core\Database\Query\AlterableInterface;
   6
   7 /**
   8  * Interface for entity queries.
   9  *
  10  * Never instantiate classes implementing this interface directly. Always use
  11  * the QueryFactory class.
  12  *
  13  * @ingroup database
  14  */
  15 interface QueryInterface extends AlterableInterface {
  16
  17   /**
  18    * Gets the ID of the entity type for this query.
  19    *
  20    * @return string
  21    */
  22   public function getEntityTypeId();
  23
  24   /**
  25    * Add a condition to the query or a condition group.
  26    *
  27    * For example, to find all entities containing both the Turkish 'merhaba'
  28    * and the Polish 'siema' within a 'greetings' text field:
  29    * @code
  30    *   $entity_ids = \Drupal::entityQuery($entity_type)
  31    *     ->condition('greetings', 'merhaba', '=', 'tr')
  32    *     ->condition('greetings.value', 'siema', '=', 'pl')
  33    *     ->execute();
  34    * @endcode
  35    *
  36    * @param $field
  37    *   Name of the field being queried. It must contain a field name, optionally
  38    *   followed by a column name. The column can be the reference property,
  39    *   usually "entity", for reference fields and that can be followed
  40    *   similarly by a field name and so on. Additionally, the target entity type
  41    *   can be specified by appending the ":target_entity_type_id" to "entity".
  42    *   Some examples:
  43    *   - nid
  44    *   - tags.value
  45    *   - tags
  46    *   - tags.entity.name
  47    *   - tags.entity:taxonomy_term.name
  48    *   - uid.entity.name
  49    *   - uid.entity:user.name
  50    *   "tags" "is the same as "tags.value" as value is the default column.
  51    *   If two or more conditions have the same field names they apply to the
  52    *   same delta within that field. In order to limit the condition to a
  53    *   specific item a numeric delta should be added between the field name and
  54    *   the column name.
  55    *   @code
  56    *   ->condition('tags.5.value', 'news')
  57    *   @endcode
  58    *   This will require condition to be satisfied on a specific delta of the
  59    *   field. The condition above will require the 6th value of the field to
  60    *   match the provided value. Further, it's possible to create a condition on
  61    *   the delta itself by using '%delta'. For example,
  62    *   @code
  63    *   ->condition('tags.%delta', 5)
  64    *   @endcode
  65    *   will find only entities which have at least six tags. Finally, the
  66    *   condition on the delta itself accompanied with a condition on the value
  67    *   will require the value to appear in the specific delta range. For
  68    *   example,
  69    *   @code
  70    *   ->condition('tags.%delta', 0, '>'))
  71    *   ->condition('tags.%delta.value', 'news'))
  72    *   @endcode
  73    *   will only find the "news" tag if it is not the first value. It should be
  74    *   noted that conditions on specific deltas and delta ranges are only
  75    *   supported when querying content entities.
  76    * @param $value
  77    *   The value for $field. In most cases, this is a scalar and it's treated as
  78    *   case-insensitive. For more complex operators, it is an array. The meaning
  79    *   of each element in the array is dependent on $operator.
  80    * @param $operator
  81    *   Possible values:
  82    *   - '=', '<>', '>', '>=', '<', '<=', 'STARTS_WITH', 'CONTAINS',
  83    *     'ENDS_WITH': These operators expect $value to be a literal of the
  84    *     same type as the column.
  85    *   - 'IN', 'NOT IN': These operators expect $value to be an array of
  86    *     literals of the same type as the column.
  87    *   - 'BETWEEN': This operator expects $value to be an array of two literals
  88    *     of the same type as the column.
  89    * @param $langcode
  90    *   Language code (optional). If omitted, any translation satisfies the
  91    *   condition. However, if two or more conditions omit the langcode within
  92    *   one condition group then they are presumed to apply to the same
  93    *   translation. If within one condition group one condition has a langcode
  94    *   and another does not they are not presumed to apply to the same
  95    *   translation.
  96    *
  97    * @return \Drupal\Core\Entity\Query\QueryInterface
  98    * @see \Drupal\Core\Entity\Query\andConditionGroup
  99    * @see \Drupal\Core\Entity\Query\orConditionGroup
 100    */
 101   public function condition($field, $value = NULL, $operator = NULL, $langcode = NULL);
 102
 103   /**
 104    * Queries for a non-empty value on a field.
 105    *
 106    * @param $field
 107    *   Name of a field.
 108    * @param $langcode
 109    *   Language code (optional).
 110    * @return \Drupal\Core\Entity\Query\QueryInterface
 111    */
 112   public function exists($field, $langcode = NULL);
 113
 114   /**
 115    * Queries for an empty field.
 116    *
 117    * @param $field
 118    *   Name of a field.
 119    * @param $langcode
 120    *   Language code (optional).
 121    * @return \Drupal\Core\Entity\Query\QueryInterface
 122    */
 123   public function notExists($field, $langcode = NULL);
 124
 125   /**
 126    * Enables a pager for the query.
 127    *
 128    * @param $limit
 129    *   An integer specifying the number of elements per page.  If passed a false
 130    *   value (FALSE, 0, NULL), the pager is disabled.
 131    * @param $element
 132    *   An optional integer to distinguish between multiple pagers on one page.
 133    *   If not provided, one is automatically calculated.
 134    *
 135    * @return \Drupal\Core\Entity\Query\QueryInterface
 136    *   The called object.
 137    */
 138   public function pager($limit = 10, $element = NULL);
 139
 140   /**
 141    * @param null $start
 142    * @param null $length
 143    * @return \Drupal\Core\Entity\Query\QueryInterface
 144    *   The called object.
 145    */
 146   public function range($start = NULL, $length = NULL);
 147
 148   /**
 149    * @param $field
 150    *   Name of a field.
 151    * @param string $direction
 152    * @param $langcode
 153    *   Language code (optional).
 154    * @return \Drupal\Core\Entity\Query\QueryInterface
 155    *   The called object.
 156    */
 157   public function sort($field, $direction = 'ASC', $langcode = NULL);
 158
 159   /**
 160    * Makes this a count query.
 161    *
 162    * For count queries, execute() returns the number entities found.
 163    *
 164    * @return \Drupal\Core\Entity\Query\QueryInterface
 165    *   The called object.
 166    */
 167   public function count();
 168
 169   /**
 170    * Enables sortable tables for this query.
 171    *
 172    * @param $headers
 173    *   An array of headers of the same structure as described in
 174    *   template_preprocess_table(). Use a 'specifier' in place of a 'field' to
 175    *   specify what to sort on. This can be an entity or a field as described
 176    *   in condition().
 177    *
 178    * @return \Drupal\Core\Entity\Query\QueryInterface
 179    *   The called object.
 180    */
 181   public function tableSort(&$headers);
 182
 183   /**
 184    * @return \Drupal\Core\Entity\Query\QueryInterface
 185    *   The called object.
 186    */
 187   public function accessCheck($access_check = TRUE);
 188
 189   /**
 190    * Execute the query.
 191    *
 192    * @return int|array
 193    *   Returns an integer for count queries or an array of ids. The values of
 194    *   the array are always entity ids. The keys will be revision ids if the
 195    *   entity supports revision and entity ids if not.
 196    */
 197   public function execute();
 198
 199   /**
 200    * Creates a new group of conditions ANDed together.
 201    *
 202    * For example, consider a drawing entity type with a 'figures' multi-value
 203    * field containing 'shape' and 'color' columns. To find all drawings
 204    * containing both a red triangle and a blue circle:
 205    * @code
 206    *   $query = \Drupal::entityQuery('drawing');
 207    *   $group = $query->andConditionGroup()
 208    *     ->condition('figures.color', 'red')
 209    *     ->condition('figures.shape', 'triangle');
 210    *   $query->condition($group);
 211    *   $group = $query->andConditionGroup()
 212    *     ->condition('figures.color', 'blue')
 213    *     ->condition('figures.shape', 'circle');
 214    *   $query->condition($group);
 215    *   $entity_ids = $query->execute();
 216    * @endcode
 217    *
 218    * @return \Drupal\Core\Entity\Query\ConditionInterface
 219    */
 220   public function andConditionGroup();
 221
 222   /**
 223    * Creates a new group of conditions ORed together.
 224    *
 225    * For example, consider a map entity with an 'attributes' field
 226    * containing 'building_type' and 'color' columns.  To find all green and
 227    * red bikesheds:
 228    * @code
 229    *   $query = \Drupal::entityQuery('map');
 230    *   $group = $query->orConditionGroup()
 231    *     ->condition('attributes.color', 'red')
 232    *     ->condition('attributes.color', 'green');
 233    *   $entity_ids = $query
 234    *     ->condition('attributes.building_type', 'bikeshed')
 235    *     ->condition($group)
 236    *     ->execute();
 237    * @endcode
 238    * Note that this particular example can be simplified:
 239    * @code
 240    *   $entity_ids = $query
 241    *     ->condition('attributes.color', array('red', 'green'))
 242    *     ->condition('attributes.building_type', 'bikeshed')
 243    *     ->execute();
 244    * @endcode
 245    *
 246    * @return \Drupal\Core\Entity\Query\ConditionInterface
 247    */
 248   public function orConditionGroup();
 249
 250   /**
 251    * Queries the current revision.
 252    *
 253    * @return $this
 254    */
 255   public function currentRevision();
 256
 257   /**
 258    * Queries the latest revision.
 259    *
 260    * The latest revision is the most recent revision of an entity. This will be
 261    * either the default revision, or a pending revision if one exists and it is
 262    * newer than the default.
 263    *
 264    * @return $this
 265    */
 266   public function latestRevision();
 267
 268   /**
 269    * Queries all the revisions.
 270    *
 271    * @return $this
 272    */
 273   public function allRevisions();
 274
 275 }