1 <?php

     2 

     3 /**

     4  * Interface for entity controller classes.

     5  *

     6  * All entity controller classes specified via the 'controller class' key

     7  * returned by hook_entity_info() or hook_entity_info_alter() have to implement

     8  * this interface.

     9  *

    10  * Most simple, SQL-based entity controllers will do better by extending

    11  * DrupalDefaultEntityController instead of implementing this interface

    12  * directly.

    13  */

    14 interface DrupalEntityControllerInterface {

    15 

    16   /**

    17    * Resets the internal, static entity cache.

    18    *

    19    * @param $ids

    20    *   (optional) If specified, the cache is reset for the entities with the

    21    *   given ids only.

    22    */

    23   public function resetCache(array $ids = NULL);

    24 

    25   /**

    26    * Loads one or more entities.

    27    *

    28    * @param $ids

    29    *   An array of entity IDs, or FALSE to load all entities.

    30    * @param $conditions

    31    *   An array of conditions. Keys are field names on the entity's base table.

    32    *   Values will be compared for equality. All the comparisons will be ANDed

    33    *   together. This parameter is deprecated; use an EntityFieldQuery instead.

    34    *

    35    * @return

    36    *   An array of entity objects indexed by their ids. When no results are

    37    *   found, an empty array is returned.

    38    */

    39   public function load($ids = array(), $conditions = array());

    40 }

    41 

    42 /**

    43  * Default implementation of DrupalEntityControllerInterface.

    44  *

    45  * This class can be used as-is by most simple entity types. Entity types

    46  * requiring special handling can extend the class.

    47  */

    48 class DrupalDefaultEntityController implements DrupalEntityControllerInterface {

    49 

    50   /**

    51    * Static cache of entities, keyed by entity ID.

    52    *

    53    * @var array

    54    */

    55   protected $entityCache;

    56 

    57   /**

    58    * Entity type for this controller instance.

    59    *

    60    * @var string

    61    */

    62   protected $entityType;

    63 

    64   /**

    65    * Array of information about the entity.

    66    *

    67    * @var array

    68    *

    69    * @see entity_get_info()

    70    */

    71   protected $entityInfo;

    72 

    73   /**

    74    * Additional arguments to pass to hook_TYPE_load().

    75    *

    76    * Set before calling DrupalDefaultEntityController::attachLoad().

    77    *

    78    * @var array

    79    */

    80   protected $hookLoadArguments;

    81 

    82   /**

    83    * Name of the entity's ID field in the entity database table.

    84    *

    85    * @var string

    86    */

    87   protected $idKey;

    88 

    89   /**

    90    * Name of entity's revision database table field, if it supports revisions.

    91    *

    92    * Has the value FALSE if this entity does not use revisions.

    93    *

    94    * @var string

    95    */

    96   protected $revisionKey;

    97 

    98   /**

    99    * The table that stores revisions, if the entity supports revisions.

   100    *

   101    * @var string

   102    */

   103   protected $revisionTable;

   104 

   105   /**

   106    * Whether this entity type should use the static cache.

   107    *

   108    * Set by entity info.

   109    *

   110    * @var boolean

   111    */

   112   protected $cache;

   113 

   114   /**

   115    * Constructor: sets basic variables.

   116    *

   117    * @param $entityType

   118    *   The entity type for which the instance is created.

   119    */

   120   public function __construct($entityType) {

   121     $this->entityType = $entityType;

   122     $this->entityInfo = entity_get_info($entityType);

   123     $this->entityCache = array();

   124     $this->hookLoadArguments = array();

   125     $this->idKey = $this->entityInfo['entity keys']['id'];

   126 

   127     // Check if the entity type supports revisions.

   128     if (!empty($this->entityInfo['entity keys']['revision'])) {

   129       $this->revisionKey = $this->entityInfo['entity keys']['revision'];

   130       $this->revisionTable = $this->entityInfo['revision table'];

   131     }

   132     else {

   133       $this->revisionKey = FALSE;

   134     }

   135 

   136     // Check if the entity type supports static caching of loaded entities.

   137     $this->cache = !empty($this->entityInfo['static cache']);

   138   }

   139 

   140   /**

   141    * Implements DrupalEntityControllerInterface::resetCache().

   142    */

   143   public function resetCache(array $ids = NULL) {

   144     if (isset($ids)) {

   145       foreach ($ids as $id) {

   146         unset($this->entityCache[$id]);

   147       }

   148     }

   149     else {

   150       $this->entityCache = array();

   151     }

   152   }

   153 

   154   /**

   155    * Implements DrupalEntityControllerInterface::load().

   156    */

   157   public function load($ids = array(), $conditions = array()) {

   158     $entities = array();

   159 

   160     // Revisions are not statically cached, and require a different query to

   161     // other conditions, so separate the revision id into its own variable.

   162     if ($this->revisionKey && isset($conditions[$this->revisionKey])) {

   163       $revision_id = $conditions[$this->revisionKey];

   164       unset($conditions[$this->revisionKey]);

   165     }

   166     else {

   167       $revision_id = FALSE;

   168     }

   169 

   170     // Create a new variable which is either a prepared version of the $ids

   171     // array for later comparison with the entity cache, or FALSE if no $ids

   172     // were passed. The $ids array is reduced as items are loaded from cache,

   173     // and we need to know if it's empty for this reason to avoid querying the

   174     // database when all requested entities are loaded from cache.

   175     $passed_ids = !empty($ids) ? array_flip($ids) : FALSE;

   176     // Try to load entities from the static cache, if the entity type supports

   177     // static caching.

   178     if ($this->cache && !$revision_id) {

   179       $entities += $this->cacheGet($ids, $conditions);

   180       // If any entities were loaded, remove them from the ids still to load.

   181       if ($passed_ids) {

   182         $ids = array_keys(array_diff_key($passed_ids, $entities));

   183       }

   184     }

   185 

   186     // Ensure integer entity IDs are valid.

   187     if (!empty($ids)) {

   188       $this->cleanIds($ids);

   189     }

   190 

   191     // Load any remaining entities from the database. This is the case if $ids

   192     // is set to FALSE (so we load all entities), if there are any ids left to

   193     // load, if loading a revision, or if $conditions was passed without $ids.

   194     if ($ids === FALSE || $ids || $revision_id || ($conditions && !$passed_ids)) {

   195       // Build the query.

   196       $query = $this->buildQuery($ids, $conditions, $revision_id);

   197       $queried_entities = $query

   198         ->execute()

   199         ->fetchAllAssoc($this->idKey);

   200     }

   201 

   202     // Pass all entities loaded from the database through $this->attachLoad(),

   203     // which attaches fields (if supported by the entity type) and calls the

   204     // entity type specific load callback, for example hook_node_load().

   205     if (!empty($queried_entities)) {

   206       $this->attachLoad($queried_entities, $revision_id);

   207       $entities += $queried_entities;

   208     }

   209 

   210     if ($this->cache) {

   211       // Add entities to the cache if we are not loading a revision.

   212       if (!empty($queried_entities) && !$revision_id) {

   213         $this->cacheSet($queried_entities);

   214       }

   215     }

   216 

   217     // Ensure that the returned array is ordered the same as the original

   218     // $ids array if this was passed in and remove any invalid ids.

   219     if ($passed_ids) {

   220       // Remove any invalid ids from the array.

   221       $passed_ids = array_intersect_key($passed_ids, $entities);

   222       foreach ($entities as $entity) {

   223         $passed_ids[$entity->{$this->idKey}] = $entity;

   224       }

   225       $entities = $passed_ids;

   226     }

   227 

   228     return $entities;

   229   }

   230 

   231   /**

   232    * Ensures integer entity IDs are valid.

   233    *

   234    * The identifier sanitization provided by this method has been introduced

   235    * as Drupal used to rely on the database to facilitate this, which worked

   236    * correctly with MySQL but led to errors with other DBMS such as PostgreSQL.

   237    *

   238    * @param array $ids

   239    *   The entity IDs to verify. Non-integer IDs are removed from this array if

   240    *   the entity type requires IDs to be integers.

   241    */

   242   protected function cleanIds(&$ids) {

   243     $entity_info = entity_get_info($this->entityType);

   244     if (isset($entity_info['base table field types'])) {

   245       $id_type = $entity_info['base table field types'][$this->idKey];

   246       if ($id_type == 'serial' || $id_type == 'int') {

   247         $ids = array_filter($ids, array($this, 'filterId'));

   248         $ids = array_map('intval', $ids);

   249       }

   250     }

   251   }

   252 

   253   /**

   254    * Callback for array_filter that removes non-integer IDs.

   255    */

   256   protected function filterId($id) {

   257     return is_numeric($id) && $id == (int) $id;

   258   }

   259 

   260   /**

   261    * Builds the query to load the entity.

   262    *

   263    * This has full revision support. For entities requiring special queries,

   264    * the class can be extended, and the default query can be constructed by

   265    * calling parent::buildQuery(). This is usually necessary when the object

   266    * being loaded needs to be augmented with additional data from another

   267    * table, such as loading node type into comments or vocabulary machine name

   268    * into terms, however it can also support $conditions on different tables.

   269    * See CommentController::buildQuery() or TaxonomyTermController::buildQuery()

   270    * for examples.

   271    *

   272    * @param $ids

   273    *   An array of entity IDs, or FALSE to load all entities.

   274    * @param $conditions

   275    *   An array of conditions. Keys are field names on the entity's base table.

   276    *   Values will be compared for equality. All the comparisons will be ANDed

   277    *   together. This parameter is deprecated; use an EntityFieldQuery instead.

   278    * @param $revision_id

   279    *   The ID of the revision to load, or FALSE if this query is asking for the

   280    *   most current revision(s).

   281    *

   282    * @return SelectQuery

   283    *   A SelectQuery object for loading the entity.

   284    */

   285   protected function buildQuery($ids, $conditions = array(), $revision_id = FALSE) {

   286     $query = db_select($this->entityInfo['base table'], 'base');

   287 

   288     $query->addTag($this->entityType . '_load_multiple');

   289 

   290     if ($revision_id) {

   291       $query->join($this->revisionTable, 'revision', "revision.{$this->idKey} = base.{$this->idKey} AND revision.{$this->revisionKey} = :revisionId", array(':revisionId' => $revision_id));

   292     }

   293     elseif ($this->revisionKey) {

   294       $query->join($this->revisionTable, 'revision', "revision.{$this->revisionKey} = base.{$this->revisionKey}");

   295     }

   296 

   297     // Add fields from the {entity} table.

   298     $entity_fields = $this->entityInfo['schema_fields_sql']['base table'];

   299 

   300     if ($this->revisionKey) {

   301       // Add all fields from the {entity_revision} table.

   302       $entity_revision_fields = drupal_map_assoc($this->entityInfo['schema_fields_sql']['revision table']);

   303       // The id field is provided by entity, so remove it.

   304       unset($entity_revision_fields[$this->idKey]);

   305 

   306       // Remove all fields from the base table that are also fields by the same

   307       // name in the revision table.

   308       $entity_field_keys = array_flip($entity_fields);

   309       foreach ($entity_revision_fields as $key => $name) {

   310         if (isset($entity_field_keys[$name])) {

   311           unset($entity_fields[$entity_field_keys[$name]]);

   312         }

   313       }

   314       $query->fields('revision', $entity_revision_fields);

   315     }

   316 

   317     $query->fields('base', $entity_fields);

   318 

   319     if ($ids) {

   320       $query->condition("base.{$this->idKey}", $ids, 'IN');

   321     }

   322     if ($conditions) {

   323       foreach ($conditions as $field => $value) {

   324         $query->condition('base.' . $field, $value);

   325       }

   326     }

   327     return $query;

   328   }

   329 

   330   /**

   331    * Attaches data to entities upon loading.

   332    *

   333    * This will attach fields, if the entity is fieldable. It calls

   334    * hook_entity_load() for modules which need to add data to all entities.

   335    * It also calls hook_TYPE_load() on the loaded entities. For example

   336    * hook_node_load() or hook_user_load(). If your hook_TYPE_load()

   337    * expects special parameters apart from the queried entities, you can set

   338    * $this->hookLoadArguments prior to calling the method.

   339    * See NodeController::attachLoad() for an example.

   340    *

   341    * @param $queried_entities

   342    *   Associative array of query results, keyed on the entity ID.

   343    * @param $revision_id

   344    *   ID of the revision that was loaded, or FALSE if the most current revision

   345    *   was loaded.

   346    */

   347   protected function attachLoad(&$queried_entities, $revision_id = FALSE) {

   348     // Attach fields.

   349     if ($this->entityInfo['fieldable']) {

   350       if ($revision_id) {

   351         field_attach_load_revision($this->entityType, $queried_entities);

   352       }

   353       else {

   354         field_attach_load($this->entityType, $queried_entities);

   355       }

   356     }

   357 

   358     // Call hook_entity_load().

   359     foreach (module_implements('entity_load') as $module) {

   360       $function = $module . '_entity_load';

   361       $function($queried_entities, $this->entityType);

   362     }

   363     // Call hook_TYPE_load(). The first argument for hook_TYPE_load() are

   364     // always the queried entities, followed by additional arguments set in

   365     // $this->hookLoadArguments.

   366     $args = array_merge(array($queried_entities), $this->hookLoadArguments);

   367     foreach (module_implements($this->entityInfo['load hook']) as $module) {

   368       call_user_func_array($module . '_' . $this->entityInfo['load hook'], $args);

   369     }

   370   }

   371 

   372   /**

   373    * Gets entities from the static cache.

   374    *

   375    * @param $ids

   376    *   If not empty, return entities that match these IDs.

   377    * @param $conditions

   378    *   If set, return entities that match all of these conditions.

   379    *

   380    * @return

   381    *   Array of entities from the entity cache.

   382    */

   383   protected function cacheGet($ids, $conditions = array()) {

   384     $entities = array();

   385     // Load any available entities from the internal cache.

   386     if (!empty($this->entityCache)) {

   387       if ($ids) {

   388         $entities += array_intersect_key($this->entityCache, array_flip($ids));

   389       }

   390       // If loading entities only by conditions, fetch all available entities

   391       // from the cache. Entities which don't match are removed later.

   392       elseif ($conditions) {

   393         $entities = $this->entityCache;

   394       }

   395     }

   396 

   397     // Exclude any entities loaded from cache if they don't match $conditions.

   398     // This ensures the same behavior whether loading from memory or database.

   399     if ($conditions) {

   400       foreach ($entities as $entity) {

   401         // Iterate over all conditions and compare them to the entity

   402         // properties. We cannot use array_diff_assoc() here since the

   403         // conditions can be nested arrays, too.

   404         foreach ($conditions as $property_name => $condition) {

   405           if (is_array($condition)) {

   406             // Multiple condition values for one property are treated as OR

   407             // operation: only if the value is not at all in the condition array

   408             // we remove the entity.

   409             if (!in_array($entity->{$property_name}, $condition)) {

   410               unset($entities[$entity->{$this->idKey}]);

   411               continue 2;

   412             }

   413           }

   414           elseif ($condition != $entity->{$property_name}) {

   415             unset($entities[$entity->{$this->idKey}]);

   416             continue 2;

   417           }

   418         }

   419       }

   420     }

   421     return $entities;

   422   }

   423 

   424   /**

   425    * Stores entities in the static entity cache.

   426    *

   427    * @param $entities

   428    *   Entities to store in the cache.

   429    */

   430   protected function cacheSet($entities) {

   431     $this->entityCache += $entities;

   432   }

   433 }

   434 

   435 /**

   436  * Exception thrown by EntityFieldQuery() on unsupported query syntax.

   437  *

   438  * Some storage modules might not support the full range of the syntax for

   439  * conditions, and will raise an EntityFieldQueryException when an unsupported

   440  * condition was specified.

   441  */

   442 class EntityFieldQueryException extends Exception {}

   443 

   444 /**

   445  * Retrieves entities matching a given set of conditions.

   446  *

   447  * This class allows finding entities based on entity properties (for example,

   448  * node->changed), field values, and generic entity meta data (bundle,

   449  * entity type, entity ID, and revision ID). It is not possible to query across

   450  * multiple entity types. For example, there is no facility to find published

   451  * nodes written by users created in the last hour, as this would require

   452  * querying both node->status and user->created.

   453  *

   454  * Normally we would not want to have public properties on the object, as that

   455  * allows the object's state to become inconsistent too easily. However, this

   456  * class's standard use case involves primarily code that does need to have

   457  * direct access to the collected properties in order to handle alternate

   458  * execution routines. We therefore use public properties for simplicity. Note

   459  * that code that is simply creating and running a field query should still use

   460  * the appropriate methods to add conditions on the query.

   461  *

   462  * Storage engines are not required to support every type of query. By default,

   463  * an EntityFieldQueryException will be raised if an unsupported condition is

   464  * specified or if the query has field conditions or sorts that are stored in

   465  * different field storage engines. However, this logic can be overridden in

   466  * hook_entity_query_alter().

   467  *

   468  * Also note that this query does not automatically respect entity access

   469  * restrictions. Node access control is performed by the SQL storage engine but

   470  * other storage engines might not do this.

   471  */

   472 class EntityFieldQuery {

   473 

   474   /**

   475    * Indicates that both deleted and non-deleted fields should be returned.

   476    *

   477    * @see EntityFieldQuery::deleted()

   478    */

   479   const RETURN_ALL = NULL;

   480 

   481   /**

   482    * TRUE if the query has already been altered, FALSE if it hasn't.

   483    *

   484    * Used in alter hooks to check for cloned queries that have already been

   485    * altered prior to the clone (for example, the pager count query).

   486    *

   487    * @var boolean

   488    */

   489   public $altered = FALSE;

   490 

   491   /**

   492    * Associative array of entity-generic metadata conditions.

   493    *

   494    * @var array

   495    *

   496    * @see EntityFieldQuery::entityCondition()

   497    */

   498   public $entityConditions = array();

   499 

   500   /**

   501    * List of field conditions.

   502    *

   503    * @var array

   504    *

   505    * @see EntityFieldQuery::fieldCondition()

   506    */

   507   public $fieldConditions = array();

   508 

   509   /**

   510    * List of field meta conditions (language and delta).

   511    *

   512    * Field conditions operate on columns specified by hook_field_schema(),

   513    * the meta conditions operate on columns added by the system: delta

   514    * and language. These can not be mixed with the field conditions because

   515    * field columns can have any name including delta and language.

   516    *

   517    * @var array

   518    *

   519    * @see EntityFieldQuery::fieldLanguageCondition()

   520    * @see EntityFieldQuery::fieldDeltaCondition()

   521    */

   522   public $fieldMetaConditions = array();

   523 

   524   /**

   525    * List of property conditions.

   526    *

   527    * @var array

   528    *

   529    * @see EntityFieldQuery::propertyCondition()

   530    */

   531   public $propertyConditions = array();

   532 

   533   /**

   534    * List of order clauses.

   535    *

   536    * @var array

   537    */

   538   public $order = array();

   539 

   540   /**

   541    * The query range.

   542    *

   543    * @var array

   544    *

   545    * @see EntityFieldQuery::range()

   546    */

   547   public $range = array();

   548 

   549   /**

   550    * The query pager data.

   551    *

   552    * @var array

   553    *

   554    * @see EntityFieldQuery::pager()

   555    */

   556   public $pager = array();

   557 

   558   /**

   559    * Query behavior for deleted data.

   560    *

   561    * TRUE to return only deleted data, FALSE to return only non-deleted data,

   562    * EntityFieldQuery::RETURN_ALL to return everything.

   563    *

   564    * @see EntityFieldQuery::deleted()

   565    */

   566   public $deleted = FALSE;

   567 

   568   /**

   569    * A list of field arrays used.

   570    *

   571    * Field names passed to EntityFieldQuery::fieldCondition() and

   572    * EntityFieldQuery::fieldOrderBy() are run through field_info_field() before

   573    * stored in this array. This way, the elements of this array are field

   574    * arrays.

   575    *

   576    * @var array

   577    */

   578   public $fields = array();

   579 

   580   /**

   581    * TRUE if this is a count query, FALSE if it isn't.

   582    *

   583    * @var boolean

   584    */

   585   public $count = FALSE;

   586 

   587   /**

   588    * Flag indicating whether this is querying current or all revisions.

   589    *

   590    * @var int

   591    *

   592    * @see EntityFieldQuery::age()

   593    */

   594   public $age = FIELD_LOAD_CURRENT;

   595 

   596   /**

   597    * A list of the tags added to this query.

   598    *

   599    * @var array

   600    *

   601    * @see EntityFieldQuery::addTag()

   602    */

   603   public $tags = array();

   604 

   605   /**

   606    * A list of metadata added to this query.

   607    *

   608    * @var array

   609    *

   610    * @see EntityFieldQuery::addMetaData()

   611    */

   612   public $metaData = array();

   613 

   614   /**

   615    * The ordered results.

   616    *

   617    * @var array

   618    *

   619    * @see EntityFieldQuery::execute().

   620    */

   621   public $orderedResults = array();

   622 

   623   /**

   624    * The method executing the query, if it is overriding the default.

   625    *

   626    * @var string

   627    *

   628    * @see EntityFieldQuery::execute().

   629    */

   630   public $executeCallback = '';

   631 

   632   /**

   633    * Adds a condition on entity-generic metadata.

   634    *

   635    * If the overall query contains only entity conditions or ordering, or if

   636    * there are property conditions, then specifying the entity type is

   637    * mandatory. If there are field conditions or ordering but no property

   638    * conditions or ordering, then specifying an entity type is optional. While

   639    * the field storage engine might support field conditions on more than one

   640    * entity type, there is no way to query across multiple entity base tables by

   641    * default. To specify the entity type, pass in 'entity_type' for $name,

   642    * the type as a string for $value, and no $operator (it's disregarded).

   643    *

   644    * 'bundle', 'revision_id' and 'entity_id' have no such restrictions.

   645    *

   646    * Note: The "comment" entity type does not support bundle conditions.

   647    *

   648    * @param $name

   649    *   'entity_type', 'bundle', 'revision_id' or 'entity_id'.

   650    * @param $value

   651    *   The value for $name. In most cases, this is a scalar. For more complex

   652    *   options, it is an array. The meaning of each element in the array is

   653    *   dependent on $operator.

   654    * @param $operator

   655    *   Possible values:

   656    *   - '=', '<>', '>', '>=', '<', '<=', 'STARTS_WITH', 'CONTAINS': These

   657    *     operators expect $value to be a literal of the same type as the

   658    *     column.

   659    *   - 'IN', 'NOT IN': These operators expect $value to be an array of

   660    *     literals of the same type as the column.

   661    *   - 'BETWEEN': This operator expects $value to be an array of two literals

   662    *     of the same type as the column.

   663    *   The operator can be omitted, and will default to 'IN' if the value is an

   664    *   array, or to '=' otherwise.

   665    *

   666    * @return EntityFieldQuery

   667    *   The called object.

   668    */

   669   public function entityCondition($name, $value, $operator = NULL) {

   670     // The '!=' operator is deprecated in favour of the '<>' operator since the

   671     // latter is ANSI SQL compatible.

   672     if ($operator == '!=') {

   673       $operator = '<>';

   674     }

   675     $this->entityConditions[$name] = array(

   676       'value' => $value,

   677       'operator' => $operator,

   678     );

   679     return $this;

   680   }

   681 

   682   /**

   683    * Adds a condition on field values.

   684    *

   685    * Note that entities with empty field values will be excluded from the

   686    * EntityFieldQuery results when using this method.

   687    *

   688    * @param $field

   689    *   Either a field name or a field array.

   690    * @param $column

   691    *   The column that should hold the value to be matched, defined in the

   692    *   hook_field_schema() of this field. If this is omitted then all of the

   693    *   other parameters are ignored, except $field, and this call will just be

   694    *   adding a condition that says that the field has a value, rather than

   695    *   testing the value itself.

   696    * @param $value

   697    *   The value to test the column value against. In most cases, this is a

   698    *   scalar. For more complex options, it is an array. The meaning of each

   699    *   element in the array is dependent on $operator.

   700    * @param $operator

   701    *   The operator to be used to test the given value. The possible values are:

   702    *   - '=', '<>', '>', '>=', '<', '<=', 'STARTS_WITH', 'CONTAINS': These

   703    *     operators expect $value to be a literal of the same type as the

   704    *     column.

   705    *   - 'IN', 'NOT IN': These operators expect $value to be an array of

   706    *     literals of the same type as the column.

   707    *   - 'BETWEEN': This operator expects $value to be an array of two literals

   708    *     of the same type as the column.

   709    *   The operator can be omitted, and will default to 'IN' if the value is an

   710    *   array, or to '=' otherwise.

   711    * @param $delta_group

   712    *   An arbitrary identifier: conditions in the same group must have the same

   713    *   $delta_group. For example, let's presume a multivalue field which has

   714    *   two columns, 'color' and 'shape', and for entity ID 1, there are two

   715    *   values: red/square and blue/circle. Entity ID 1 does not have values

   716    *   corresponding to 'red circle'; however if you pass 'red' and 'circle' as

   717    *   conditions, it will appear in the results -- by default queries will run

   718    *   against any combination of deltas. By passing the conditions with the

   719    *   same $delta_group it will ensure that only values attached to the same

   720    *   delta are matched, and entity 1 would then be excluded from the results.

   721    * @param $language_group

   722    *   An arbitrary identifier: conditions in the same group must have the same

   723    *   $language_group.

   724    *

   725    * @return EntityFieldQuery

   726    *   The called object.

   727    *

   728    * @see EntityFieldQuery::addFieldCondition

   729    * @see EntityFieldQuery::deleted

   730    */

   731   public function fieldCondition($field, $column = NULL, $value = NULL, $operator = NULL, $delta_group = NULL, $language_group = NULL) {

   732     return $this->addFieldCondition($this->fieldConditions, $field, $column, $value, $operator, $delta_group, $language_group);

   733   }

   734 

   735   /**

   736    * Adds a condition on the field language column.

   737    *

   738    * @param $field

   739    *   Either a field name or a field array.

   740    * @param $value

   741    *   The value to test the column value against.

   742    * @param $operator

   743    *   The operator to be used to test the given value.

   744    * @param $delta_group

   745    *   An arbitrary identifier: conditions in the same group must have the same

   746    *   $delta_group.

   747    * @param $language_group

   748    *   An arbitrary identifier: conditions in the same group must have the same

   749    *   $language_group.

   750    *

   751    * @return EntityFieldQuery

   752    *   The called object.

   753    *

   754    * @see EntityFieldQuery::addFieldCondition

   755    * @see EntityFieldQuery::deleted

   756    */

   757   public function fieldLanguageCondition($field, $value = NULL, $operator = NULL, $delta_group = NULL, $language_group = NULL) {

   758     return $this->addFieldCondition($this->fieldMetaConditions, $field, 'language', $value, $operator, $delta_group, $language_group);

   759   }

   760 

   761   /**

   762    * Adds a condition on the field delta column.

   763    *

   764    * @param $field

   765    *   Either a field name or a field array.

   766    * @param $value

   767    *   The value to test the column value against.

   768    * @param $operator

   769    *   The operator to be used to test the given value.

   770    * @param $delta_group

   771    *   An arbitrary identifier: conditions in the same group must have the same

   772    *   $delta_group.

   773    * @param $language_group

   774    *   An arbitrary identifier: conditions in the same group must have the same

   775    *   $language_group.

   776    *

   777    * @return EntityFieldQuery

   778    *   The called object.

   779    *

   780    * @see EntityFieldQuery::addFieldCondition

   781    * @see EntityFieldQuery::deleted

   782    */

   783   public function fieldDeltaCondition($field, $value = NULL, $operator = NULL, $delta_group = NULL, $language_group = NULL) {

   784     return $this->addFieldCondition($this->fieldMetaConditions, $field, 'delta', $value, $operator, $delta_group, $language_group);

   785   }

   786 

   787   /**

   788    * Adds the given condition to the proper condition array.

   789    *

   790    * @param $conditions

   791    *   A reference to an array of conditions.

   792    * @param $field

   793    *   Either a field name or a field array.

   794    * @param $column

   795    *   The column that should hold the value to be matched, defined in the

   796    *   hook_field_schema() of this field. If this is omitted then all of the

   797    *   other parameters are ignored, except $field, and this call will just be

   798    *   adding a condition that says that the field has a value, rather than

   799    *   testing the value itself.

   800    * @param $value

   801    *   The value to test the column value against. In most cases, this is a

   802    *   scalar. For more complex options, it is an array. The meaning of each

   803    *   element in the array is dependent on $operator.

   804    * @param $operator

   805    *   Possible values:

   806    *   - '=', '<>', '>', '>=', '<', '<=', 'STARTS_WITH', 'CONTAINS': These

   807    *     operators expect $value to be a literal of the same type as the

   808    *     column.

   809    *   - 'IN', 'NOT IN': These operators expect $value to be an array of

   810    *     literals of the same type as the column.

   811    *   - 'BETWEEN': This operator expects $value to be an array of two literals

   812    *     of the same type as the column.

   813    *   The operator can be omitted, and will default to 'IN' if the value is an

   814    *   array, or to '=' otherwise.

   815    * @param $delta_group

   816    *   An arbitrary identifier: conditions in the same group must have the same

   817    *   $delta_group. For example, let's presume a multivalue field which has

   818    *   two columns, 'color' and 'shape', and for entity ID 1, there are two

   819    *   values: red/square and blue/circle. Entity ID 1 does not have values

   820    *   corresponding to 'red circle', however if you pass 'red' and 'circle' as

   821    *   conditions, it will appear in the results -- by default queries will run

   822    *   against any combination of deltas. By passing the conditions with the

   823    *   same $delta_group it will ensure that only values attached to the same

   824    *   delta are matched, and entity 1 would then be excluded from the results.

   825    * @param $language_group

   826    *   An arbitrary identifier: conditions in the same group must have the same

   827    *   $language_group.

   828    *

   829    * @return EntityFieldQuery

   830    *   The called object.

   831    */

   832   protected function addFieldCondition(&$conditions, $field, $column = NULL, $value = NULL, $operator = NULL, $delta_group = NULL, $language_group = NULL) {

   833     // The '!=' operator is deprecated in favour of the '<>' operator since the

   834     // latter is ANSI SQL compatible.

   835     if ($operator == '!=') {

   836       $operator = '<>';

   837     }

   838     if (is_scalar($field)) {

   839       $field_definition = field_info_field($field);

   840       if (empty($field_definition)) {

   841         throw new EntityFieldQueryException(t('Unknown field: @field_name', array('@field_name' => $field)));

   842       }

   843       $field = $field_definition;

   844     }

   845     // Ensure the same index is used for field conditions as for fields.

   846     $index = count($this->fields);

   847     $this->fields[$index] = $field;

   848     if (isset($column)) {

   849       $conditions[$index] = array(

   850         'field' => $field,

   851         'column' => $column,

   852         'value' => $value,

   853         'operator' => $operator,

   854         'delta_group' => $delta_group,

   855         'language_group' => $language_group,

   856       );

   857     }

   858     return $this;

   859   }

   860 

   861   /**

   862    * Adds a condition on an entity-specific property.

   863    *

   864    * An $entity_type must be specified by calling

   865    * EntityFieldCondition::entityCondition('entity_type', $entity_type) before

   866    * executing the query. Also, by default only entities stored in SQL are

   867    * supported; however, EntityFieldQuery::executeCallback can be set to handle

   868    * different entity storage.

   869    *

   870    * @param $column

   871    *   A column defined in the hook_schema() of the base table of the entity.

   872    * @param $value

   873    *   The value to test the field against. In most cases, this is a scalar. For

   874    *   more complex options, it is an array. The meaning of each element in the

   875    *   array is dependent on $operator.

   876    * @param $operator

   877    *   Possible values:

   878    *   - '=', '<>', '>', '>=', '<', '<=', 'STARTS_WITH', 'CONTAINS': These

   879    *     operators expect $value to be a literal of the same type as the

   880    *     column.

   881    *   - 'IN', 'NOT IN': These operators expect $value to be an array of

   882    *     literals of the same type as the column.

   883    *   - 'BETWEEN': This operator expects $value to be an array of two literals

   884    *     of the same type as the column.

   885    *   The operator can be omitted, and will default to 'IN' if the value is an

   886    *   array, or to '=' otherwise.

   887    *

   888    * @return EntityFieldQuery

   889    *   The called object.

   890    */

   891   public function propertyCondition($column, $value, $operator = NULL) {

   892     // The '!=' operator is deprecated in favour of the '<>' operator since the

   893     // latter is ANSI SQL compatible.

   894     if ($operator == '!=') {

   895       $operator = '<>';

   896     }

   897     $this->propertyConditions[] = array(

   898       'column' => $column,

   899       'value' => $value,

   900       'operator' => $operator,

   901     );

   902     return $this;

   903   }

   904 

   905   /**

   906    * Orders the result set by entity-generic metadata.

   907    *

   908    * If called multiple times, the query will order by each specified column in

   909    * the order this method is called.

   910    *

   911    * Note: The "comment" and "taxonomy_term" entity types don't support ordering

   912    * by bundle. For "taxonomy_term", propertyOrderBy('vid') can be used instead.

   913    *

   914    * @param $name

   915    *   'entity_type', 'bundle', 'revision_id' or 'entity_id'.

   916    * @param $direction

   917    *   The direction to sort. Legal values are "ASC" and "DESC".

   918    *

   919    * @return EntityFieldQuery

   920    *   The called object.

   921    */

   922   public function entityOrderBy($name, $direction = 'ASC') {

   923     $this->order[] = array(

   924       'type' => 'entity',

   925       'specifier' => $name,

   926       'direction' => $direction,

   927     );

   928     return $this;

   929   }

   930 

   931   /**

   932    * Orders the result set by a given field column.

   933    *

   934    * If called multiple times, the query will order by each specified column in

   935    * the order this method is called. Note that entities with empty field

   936    * values will be excluded from the EntityFieldQuery results when using this

   937    * method.

   938    *

   939    * @param $field

   940    *   Either a field name or a field array.

   941    * @param $column

   942    *   A column defined in the hook_field_schema() of this field. entity_id and

   943    *   bundle can also be used.

   944    * @param $direction

   945    *   The direction to sort. Legal values are "ASC" and "DESC".

   946    *

   947    * @return EntityFieldQuery

   948    *   The called object.

   949    */

   950   public function fieldOrderBy($field, $column, $direction = 'ASC') {

   951     if (is_scalar($field)) {

   952       $field_definition = field_info_field($field);

   953       if (empty($field_definition)) {

   954         throw new EntityFieldQueryException(t('Unknown field: @field_name', array('@field_name' => $field)));

   955       }

   956       $field = $field_definition;

   957     }

   958     // Save the index used for the new field, for later use in field storage.

   959     $index = count($this->fields);

   960     $this->fields[$index] = $field;

   961     $this->order[] = array(

   962       'type' => 'field',

   963       'specifier' => array(

   964         'field' => $field,

   965         'index' => $index,

   966         'column' => $column,

   967       ),

   968       'direction' => $direction,

   969     );

   970     return $this;

   971   }

   972 

   973   /**

   974    * Orders the result set by an entity-specific property.

   975    *

   976    * An $entity_type must be specified by calling

   977    * EntityFieldCondition::entityCondition('entity_type', $entity_type) before

   978    * executing the query.

   979    *

   980    * If called multiple times, the query will order by each specified column in

   981    * the order this method is called.

   982    *

   983    * @param $column

   984    *   The column on which to order.

   985    * @param $direction

   986    *   The direction to sort. Legal values are "ASC" and "DESC".

   987    *

   988    * @return EntityFieldQuery

   989    *   The called object.

   990    */

   991   public function propertyOrderBy($column, $direction = 'ASC') {

   992     $this->order[] = array(

   993       'type' => 'property',

   994       'specifier' => $column,

   995       'direction' => $direction,

   996     );

   997     return $this;

   998   }

   999 

  1000   /**

  1001    * Sets the query to be a count query only.

  1002    *

  1003    * @return EntityFieldQuery

  1004    *   The called object.

  1005    */

  1006   public function count() {

  1007     $this->count = TRUE;

  1008     return $this;

  1009   }

  1010 

  1011   /**

  1012    * Restricts a query to a given range in the result set.

  1013    *

  1014    * @param $start

  1015    *   The first entity from the result set to return. If NULL, removes any

  1016    *   range directives that are set.

  1017    * @param $length

  1018    *   The number of entities to return from the result set.

  1019    *

  1020    * @return EntityFieldQuery

  1021    *   The called object.

  1022    */

  1023   public function range($start = NULL, $length = NULL) {

  1024     $this->range = array(

  1025       'start' => $start,

  1026       'length' => $length,

  1027     );

  1028     return $this;

  1029   }

  1030 

  1031   /**

  1032    * Enables a pager for the query.

  1033    *

  1034    * @param $limit

  1035    *   An integer specifying the number of elements per page.  If passed a false

  1036    *   value (FALSE, 0, NULL), the pager is disabled.

  1037    * @param $element

  1038    *   An optional integer to distinguish between multiple pagers on one page.

  1039    *   If not provided, one is automatically calculated.

  1040    *

  1041    * @return EntityFieldQuery

  1042    *   The called object.

  1043    */

  1044   public function pager($limit = 10, $element = NULL) {

  1045     if (!isset($element)) {

  1046       $element = PagerDefault::$maxElement++;

  1047     }

  1048     elseif ($element >= PagerDefault::$maxElement) {

  1049       PagerDefault::$maxElement = $element + 1;

  1050     }

  1051 

  1052     $this->pager = array(

  1053       'limit' => $limit,

  1054       'element' => $element,

  1055     );

  1056     return $this;

  1057   }

  1058 

  1059   /**

  1060    * Enables sortable tables for this query.

  1061    *

  1062    * @param $headers

  1063    *   An EFQ Header array based on which the order clause is added to the

  1064    *   query.

  1065    *

  1066    * @return EntityFieldQuery

  1067    *   The called object.

  1068    */

  1069   public function tableSort(&$headers) {

  1070     // If 'field' is not initialized, the header columns aren't clickable

  1071     foreach ($headers as $key =>$header) {

  1072       if (is_array($header) && isset($header['specifier'])) {

  1073         $headers[$key]['field'] = '';

  1074       }

  1075     }

  1076 

  1077     $order = tablesort_get_order($headers);

  1078     $direction = tablesort_get_sort($headers);

  1079     foreach ($headers as $header) {

  1080       if (is_array($header) && ($header['data'] == $order['name'])) {

  1081         if ($header['type'] == 'field') {

  1082           $this->fieldOrderBy($header['specifier']['field'], $header['specifier']['column'], $direction);

  1083         }

  1084         else {

  1085           $header['direction'] = $direction;

  1086           $this->order[] = $header;

  1087         }

  1088       }

  1089     }

  1090 

  1091     return $this;

  1092   }

  1093 

  1094   /**

  1095    * Filters on the data being deleted.

  1096    *

  1097    * @param $deleted

  1098    *   TRUE to only return deleted data, FALSE to return non-deleted data,

  1099    *   EntityFieldQuery::RETURN_ALL to return everything. Defaults to FALSE.

  1100    *

  1101    * @return EntityFieldQuery

  1102    *   The called object.

  1103    */

  1104   public function deleted($deleted = TRUE) {

  1105     $this->deleted = $deleted;

  1106     return $this;

  1107   }

  1108 

  1109   /**

  1110    * Queries the current or every revision.

  1111    *

  1112    * Note that this only affects field conditions. Property conditions always

  1113    * apply to the current revision.

  1114    * @TODO: Once revision tables have been cleaned up, revisit this.

  1115    *

  1116    * @param $age

  1117    *   - FIELD_LOAD_CURRENT (default): Query the most recent revisions for all

  1118    *     entities. The results will be keyed by entity type and entity ID.

  1119    *   - FIELD_LOAD_REVISION: Query all revisions. The results will be keyed by

  1120    *     entity type and entity revision ID.

  1121    *

  1122    * @return EntityFieldQuery

  1123    *   The called object.

  1124    */

  1125   public function age($age) {

  1126     $this->age = $age;

  1127     return $this;

  1128   }

  1129 

  1130   /**

  1131    * Adds a tag to the query.

  1132    *

  1133    * Tags are strings that mark a query so that hook_query_alter() and

  1134    * hook_query_TAG_alter() implementations may decide if they wish to alter

  1135    * the query. A query may have any number of tags, and they must be valid PHP

  1136    * identifiers (composed of letters, numbers, and underscores). For example,