QueryInterface.php 7.36 KB
Newer Older
1 2 3 4
<?php

/**
 * @file
5
 * Contains \Drupal\Core\Entity\QueryInterface.
6 7 8 9
 */

namespace Drupal\Core\Entity\Query;

10 11
use Drupal\Core\Database\Query\AlterableInterface;

12 13 14 15 16 17
/**
 * Interface for entity queries.
 *
 * Never instantiate classes implementing this interface directly. Always use
 * the QueryFactory class.
 */
18
interface QueryInterface extends AlterableInterface {
19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39

  /**
   * Gets the entity type for this query.
   *
   * @return string
   */
  public function getEntityType();

  /**
   * Add a condition to the query or a condition group.
   *
   * @param $field
   *   Name of the field being queried.
   *   Some examples:
   *   - nid
   *   - tags.value
   *   - tags this is the same as tags.value as .value is the default.
   *
   * For example, to find all entities containing both the Turkish 'merhaba'
   * and the Polish 'siema' within a 'greetings' text field:
   * @code
40
   *   $entity_ids = Drupal::entityQuery($entity_type)
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200
   *     ->condition('greetings', 'merhaba', '=', 'tr');
   *     ->condition('greetings.value', 'siema', '=', 'pl');
   *     ->execute();
   *   $entity_ids = $query->execute();
   * @endcode
   *
   * @param $value
   *   The value for $field. In most cases, this is a scalar. For more complex
   *   options, it is an array. The meaning of each element in the array is
   *   dependent on $operator.
   * @param $operator
   *   Possible values:
   *   - '=', '<>', '>', '>=', '<', '<=', 'STARTS_WITH', 'CONTAINS',
   *     'ENDS_WITH': These operators expect $value to be a literal of the
   *     same type as the column.
   *   - 'IN', 'NOT IN': These operators expect $value to be an array of
   *     literals of the same type as the column.
   *   - 'BETWEEN': This operator expects $value to be an array of two literals
   *     of the same type as the column.
   * @param $langcode
   *   Language code (optional).
   *
   * @return \Drupal\Core\Entity\Query\QueryInterface
   * @see Drupal\Core\Entity\Query\andConditionGroup
   * @see Drupal\Core\Entity\Query\orConditionGroup
   */
  public function condition($field, $value = NULL, $operator = NULL, $langcode = NULL);

  /**
   * Queries for the existence of a field.
   *
   * @param $field
   *   Name of a field.
   * @param $langcode
   *   Language code (optional).
   * @return \Drupal\Core\Entity\Query\QueryInterface
   */
  public function exists($field, $langcode = NULL);

  /**
   * Queries for the nonexistence of a field.
   *
   * @param $field.
   *   Name of a field.
   * @param $langcode
   *   Language code (optional).
   * @return \Drupal\Core\Entity\Query\QueryInterface
   */
  public function notExists($field, $langcode = NULL);

  /**
   * Enables a pager for the query.
   *
   * @param $limit
   *   An integer specifying the number of elements per page.  If passed a false
   *   value (FALSE, 0, NULL), the pager is disabled.
   * @param $element
   *   An optional integer to distinguish between multiple pagers on one page.
   *   If not provided, one is automatically calculated.
   *
   * @return \Drupal\Core\Entity\Query\QueryInterface
   *   The called object.
   */
  public function pager($limit = 10, $element = NULL);

  /**
   * @param null $start
   * @param null $length
   * @return \Drupal\Core\Entity\Query\QueryInterface
   *   The called object.
   */
  public function range($start = NULL, $length = NULL);

  /**
   * @param $field
   *   Name of a field.
   * @param string $direction
   * @param $langcode
   *   Language code (optional).
   * @return \Drupal\Core\Entity\Query\QueryInterface
   *   The called object.
   */
  public function sort($field, $direction = 'ASC', $langcode = NULL);

  /**
   * Makes this a count query.
   *
   * For count queries, execute() returns the number entities found.
   *
   * @return \Drupal\Core\Entity\Query\QueryInterface
   *   The called object.
   */
  public function count();

  /**
   * Enables sortable tables for this query.
   *
   * @param $headers
   *   An array of headers of the same struucture as described in
   *   theme_table(). Use a 'specifier' in place of a 'field' to specify what
   *   to sort on. This can be an entity or a field as described in
   *   condition().
   * @return \Drupal\Core\Entity\Query\QueryInterface
   *   The called object.
   */
  public function tableSort(&$headers);

  /**
   * @return \Drupal\Core\Entity\Query\QueryInterface
   *   The called object.
   */
  public function accessCheck($access_check = TRUE);

  /**
   * Queries the current or every revision.
   *
   * Note that this only affects field conditions. Property conditions always
   * apply to the current revision.
   * @TODO: Once revision tables have been cleaned up, revisit this.
   *
   * @param $age
   *   - FIELD_LOAD_CURRENT (default): Query the most recent revisions only,
   *   - FIELD_LOAD_REVISION: Query all revisions.
   *
   * @return \Drupal\Core\Entity\Query\QueryInterface
   *   The called object.
   */
  public function age($age = FIELD_LOAD_CURRENT);

  /**
   * Execute the query.
   *
   * @return int|array
   *   Returns an integer for count queries or an array of ids. The values of
   *   the array are always entity ids. The keys will be revision ids if the
   *   entity supports revision and entity ids if not.
   */
  public function execute();

  /**
   * Creates an object holding a group of conditions.
   *
   * See andConditionGroup() and orConditionGroup() for more.
   *
   * @param $conjunction
   *   - AND (default): this is the equivalent of andConditionGroup().
   *   - OR: this is the equivalent of andConditionGroup().
   *
   * return ConditionInterface
   *   An object holding a group of conditions.
   */
  public function conditionGroupFactory($conjunction = 'AND');

  /**
   * Creates a new group of conditions ANDed together.
   *
   * For example, consider a drawing entity type with a 'figures' multi-value
   * field containing 'shape' and 'color' columns. To find all drawings
   * containing both a red triangle and a blue circle:
   * @code
201
   *   $query = Drupal::entityQuery('drawing');
202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223
   *   $group = $query->andConditionGroup()
   *     ->condition('figures.color', 'red')
   *     ->condition('figures.shape', 'triangle');
   *   $query->condition($group);
   *   $group = $query->andConditionGroup()
   *     ->condition('figures.color', 'blue')
   *     ->condition('figures.shape', 'circle');
   *   $query->condition($group);
   *   $entity_ids = $query->execute();
   * @endcode
   *
   * @return \Drupal\Core\Entity\Query\ConditionInterface
   */
  public function andConditionGroup();

  /**
   * Creates a new group of conditions ORed together.
   *
   * For example, consider a map entity with an 'attributes' field
   * containing 'building_type' and 'color' columns.  To find all green and
   * red bikesheds:
   * @code
224
   *   $query = Drupal::entityQuery('map');
225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245
   *   $group = $query->orConditionGroup()
   *     ->condition('attributes.color', 'red')
   *     ->condition('attributes.color', 'green');
   *   $entity_ids = $query
   *     ->condition('attributes.building_type', 'bikeshed')
   *     ->condition($group)
   *     ->execute();
   * @endcode
   * Note that this particular example can be simplified:
   * @code
   *   $entity_ids = $query
   *     ->condition('attributes.color', array('red', 'green'))
   *     ->condition('attributes.building_type', 'bikeshed')
   *     ->execute();
   * @endcode
   *
   * @return \Drupal\Core\Entity\Query\ConditionInterface
   */
  public function orConditionGroup();

}