12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412 |
- <?php
- /**
- * Interface for entity controller classes.
- *
- * All entity controller classes specified via the 'controller class' key
- * returned by hook_entity_info() or hook_entity_info_alter() have to implement
- * this interface.
- *
- * Most simple, SQL-based entity controllers will do better by extending
- * DrupalDefaultEntityController instead of implementing this interface
- * directly.
- */
- interface DrupalEntityControllerInterface {
- /**
- * Resets the internal, static entity cache.
- *
- * @param $ids
- * (optional) If specified, the cache is reset for the entities with the
- * given ids only.
- */
- public function resetCache(array $ids = NULL);
- /**
- * Loads one or more entities.
- *
- * @param $ids
- * An array of entity IDs, or FALSE to load all entities.
- * @param $conditions
- * An array of conditions. Keys are field names on the entity's base table.
- * Values will be compared for equality. All the comparisons will be ANDed
- * together. This parameter is deprecated; use an EntityFieldQuery instead.
- *
- * @return
- * An array of entity objects indexed by their ids. When no results are
- * found, an empty array is returned.
- */
- public function load($ids = array(), $conditions = array());
- }
- /**
- * Default implementation of DrupalEntityControllerInterface.
- *
- * This class can be used as-is by most simple entity types. Entity types
- * requiring special handling can extend the class.
- */
- class DrupalDefaultEntityController implements DrupalEntityControllerInterface {
- /**
- * Static cache of entities, keyed by entity ID.
- *
- * @var array
- */
- protected $entityCache;
- /**
- * Entity type for this controller instance.
- *
- * @var string
- */
- protected $entityType;
- /**
- * Array of information about the entity.
- *
- * @var array
- *
- * @see entity_get_info()
- */
- protected $entityInfo;
- /**
- * Additional arguments to pass to hook_TYPE_load().
- *
- * Set before calling DrupalDefaultEntityController::attachLoad().
- *
- * @var array
- */
- protected $hookLoadArguments;
- /**
- * Name of the entity's ID field in the entity database table.
- *
- * @var string
- */
- protected $idKey;
- /**
- * Name of entity's revision database table field, if it supports revisions.
- *
- * Has the value FALSE if this entity does not use revisions.
- *
- * @var string
- */
- protected $revisionKey;
- /**
- * The table that stores revisions, if the entity supports revisions.
- *
- * @var string
- */
- protected $revisionTable;
- /**
- * Whether this entity type should use the static cache.
- *
- * Set by entity info.
- *
- * @var boolean
- */
- protected $cache;
- /**
- * Constructor: sets basic variables.
- *
- * @param $entityType
- * The entity type for which the instance is created.
- */
- public function __construct($entityType) {
- $this->entityType = $entityType;
- $this->entityInfo = entity_get_info($entityType);
- $this->entityCache = array();
- $this->hookLoadArguments = array();
- $this->idKey = $this->entityInfo['entity keys']['id'];
- // Check if the entity type supports revisions.
- if (!empty($this->entityInfo['entity keys']['revision'])) {
- $this->revisionKey = $this->entityInfo['entity keys']['revision'];
- $this->revisionTable = $this->entityInfo['revision table'];
- }
- else {
- $this->revisionKey = FALSE;
- }
- // Check if the entity type supports static caching of loaded entities.
- $this->cache = !empty($this->entityInfo['static cache']);
- }
- /**
- * Implements DrupalEntityControllerInterface::resetCache().
- */
- public function resetCache(array $ids = NULL) {
- if (isset($ids)) {
- foreach ($ids as $id) {
- unset($this->entityCache[$id]);
- }
- }
- else {
- $this->entityCache = array();
- }
- }
- /**
- * Implements DrupalEntityControllerInterface::load().
- */
- public function load($ids = array(), $conditions = array()) {
- $entities = array();
- // Revisions are not statically cached, and require a different query to
- // other conditions, so separate the revision id into its own variable.
- if ($this->revisionKey && isset($conditions[$this->revisionKey])) {
- $revision_id = $conditions[$this->revisionKey];
- unset($conditions[$this->revisionKey]);
- }
- else {
- $revision_id = FALSE;
- }
- // Create a new variable which is either a prepared version of the $ids
- // array for later comparison with the entity cache, or FALSE if no $ids
- // were passed. The $ids array is reduced as items are loaded from cache,
- // and we need to know if it's empty for this reason to avoid querying the
- // database when all requested entities are loaded from cache.
- $passed_ids = !empty($ids) ? array_flip($ids) : FALSE;
- // Try to load entities from the static cache, if the entity type supports
- // static caching.
- if ($this->cache && !$revision_id) {
- $entities += $this->cacheGet($ids, $conditions);
- // If any entities were loaded, remove them from the ids still to load.
- if ($passed_ids) {
- $ids = array_keys(array_diff_key($passed_ids, $entities));
- }
- }
- // Ensure integer entity IDs are valid.
- if (!empty($ids)) {
- $this->cleanIds($ids);
- }
- // Load any remaining entities from the database. This is the case if $ids
- // is set to FALSE (so we load all entities), if there are any ids left to
- // load, if loading a revision, or if $conditions was passed without $ids.
- if ($ids === FALSE || $ids || $revision_id || ($conditions && !$passed_ids)) {
- // Build the query.
- $query = $this->buildQuery($ids, $conditions, $revision_id);
- $queried_entities = $query
- ->execute()
- ->fetchAllAssoc($this->idKey);
- }
- // Pass all entities loaded from the database through $this->attachLoad(),
- // which attaches fields (if supported by the entity type) and calls the
- // entity type specific load callback, for example hook_node_load().
- if (!empty($queried_entities)) {
- $this->attachLoad($queried_entities, $revision_id);
- $entities += $queried_entities;
- }
- if ($this->cache) {
- // Add entities to the cache if we are not loading a revision.
- if (!empty($queried_entities) && !$revision_id) {
- $this->cacheSet($queried_entities);
- }
- }
- // Ensure that the returned array is ordered the same as the original
- // $ids array if this was passed in and remove any invalid ids.
- if ($passed_ids) {
- // Remove any invalid ids from the array.
- $passed_ids = array_intersect_key($passed_ids, $entities);
- foreach ($entities as $entity) {
- $passed_ids[$entity->{$this->idKey}] = $entity;
- }
- $entities = $passed_ids;
- }
- return $entities;
- }
- /**
- * Ensures integer entity IDs are valid.
- *
- * The identifier sanitization provided by this method has been introduced
- * as Drupal used to rely on the database to facilitate this, which worked
- * correctly with MySQL but led to errors with other DBMS such as PostgreSQL.
- *
- * @param array $ids
- * The entity IDs to verify. Non-integer IDs are removed from this array if
- * the entity type requires IDs to be integers.
- */
- protected function cleanIds(&$ids) {
- $entity_info = entity_get_info($this->entityType);
- if (isset($entity_info['base table field types'])) {
- $id_type = $entity_info['base table field types'][$this->idKey];
- if ($id_type == 'serial' || $id_type == 'int') {
- $ids = array_filter($ids, array($this, 'filterId'));
- $ids = array_map('intval', $ids);
- }
- }
- }
- /**
- * Callback for array_filter that removes non-integer IDs.
- */
- protected function filterId($id) {
- return is_numeric($id) && $id == (int) $id;
- }
- /**
- * Builds the query to load the entity.
- *
- * This has full revision support. For entities requiring special queries,
- * the class can be extended, and the default query can be constructed by
- * calling parent::buildQuery(). This is usually necessary when the object
- * being loaded needs to be augmented with additional data from another
- * table, such as loading node type into comments or vocabulary machine name
- * into terms, however it can also support $conditions on different tables.
- * See CommentController::buildQuery() or TaxonomyTermController::buildQuery()
- * for examples.
- *
- * @param $ids
- * An array of entity IDs, or FALSE to load all entities.
- * @param $conditions
- * An array of conditions. Keys are field names on the entity's base table.
- * Values will be compared for equality. All the comparisons will be ANDed
- * together. This parameter is deprecated; use an EntityFieldQuery instead.
- * @param $revision_id
- * The ID of the revision to load, or FALSE if this query is asking for the
- * most current revision(s).
- *
- * @return SelectQuery
- * A SelectQuery object for loading the entity.
- */
- protected function buildQuery($ids, $conditions = array(), $revision_id = FALSE) {
- $query = db_select($this->entityInfo['base table'], 'base');
- $query->addTag($this->entityType . '_load_multiple');
- if ($revision_id) {
- $query->join($this->revisionTable, 'revision', "revision.{$this->idKey} = base.{$this->idKey} AND revision.{$this->revisionKey} = :revisionId", array(':revisionId' => $revision_id));
- }
- elseif ($this->revisionKey) {
- $query->join($this->revisionTable, 'revision', "revision.{$this->revisionKey} = base.{$this->revisionKey}");
- }
- // Add fields from the {entity} table.
- $entity_fields = $this->entityInfo['schema_fields_sql']['base table'];
- if ($this->revisionKey) {
- // Add all fields from the {entity_revision} table.
- $entity_revision_fields = drupal_map_assoc($this->entityInfo['schema_fields_sql']['revision table']);
- // The id field is provided by entity, so remove it.
- unset($entity_revision_fields[$this->idKey]);
- // Remove all fields from the base table that are also fields by the same
- // name in the revision table.
- $entity_field_keys = array_flip($entity_fields);
- foreach ($entity_revision_fields as $key => $name) {
- if (isset($entity_field_keys[$name])) {
- unset($entity_fields[$entity_field_keys[$name]]);
- }
- }
- $query->fields('revision', $entity_revision_fields);
- }
- $query->fields('base', $entity_fields);
- if ($ids) {
- $query->condition("base.{$this->idKey}", $ids, 'IN');
- }
- if ($conditions) {
- foreach ($conditions as $field => $value) {
- $query->condition('base.' . $field, $value);
- }
- }
- return $query;
- }
- /**
- * Attaches data to entities upon loading.
- *
- * This will attach fields, if the entity is fieldable. It calls
- * hook_entity_load() for modules which need to add data to all entities.
- * It also calls hook_TYPE_load() on the loaded entities. For example
- * hook_node_load() or hook_user_load(). If your hook_TYPE_load()
- * expects special parameters apart from the queried entities, you can set
- * $this->hookLoadArguments prior to calling the method.
- * See NodeController::attachLoad() for an example.
- *
- * @param $queried_entities
- * Associative array of query results, keyed on the entity ID.
- * @param $revision_id
- * ID of the revision that was loaded, or FALSE if the most current revision
- * was loaded.
- */
- protected function attachLoad(&$queried_entities, $revision_id = FALSE) {
- // Attach fields.
- if ($this->entityInfo['fieldable']) {
- if ($revision_id) {
- field_attach_load_revision($this->entityType, $queried_entities);
- }
- else {
- field_attach_load($this->entityType, $queried_entities);
- }
- }
- // Call hook_entity_load().
- foreach (module_implements('entity_load') as $module) {
- $function = $module . '_entity_load';
- $function($queried_entities, $this->entityType);
- }
- // Call hook_TYPE_load(). The first argument for hook_TYPE_load() are
- // always the queried entities, followed by additional arguments set in
- // $this->hookLoadArguments.
- $args = array_merge(array($queried_entities), $this->hookLoadArguments);
- foreach (module_implements($this->entityInfo['load hook']) as $module) {
- call_user_func_array($module . '_' . $this->entityInfo['load hook'], $args);
- }
- }
- /**
- * Gets entities from the static cache.
- *
- * @param $ids
- * If not empty, return entities that match these IDs.
- * @param $conditions
- * If set, return entities that match all of these conditions.
- *
- * @return
- * Array of entities from the entity cache.
- */
- protected function cacheGet($ids, $conditions = array()) {
- $entities = array();
- // Load any available entities from the internal cache.
- if (!empty($this->entityCache)) {
- if ($ids) {
- $entities += array_intersect_key($this->entityCache, array_flip($ids));
- }
- // If loading entities only by conditions, fetch all available entities
- // from the cache. Entities which don't match are removed later.
- elseif ($conditions) {
- $entities = $this->entityCache;
- }
- }
- // Exclude any entities loaded from cache if they don't match $conditions.
- // This ensures the same behavior whether loading from memory or database.
- if ($conditions) {
- foreach ($entities as $entity) {
- // Iterate over all conditions and compare them to the entity
- // properties. We cannot use array_diff_assoc() here since the
- // conditions can be nested arrays, too.
- foreach ($conditions as $property_name => $condition) {
- if (is_array($condition)) {
- // Multiple condition values for one property are treated as OR
- // operation: only if the value is not at all in the condition array
- // we remove the entity.
- if (!in_array($entity->{$property_name}, $condition)) {
- unset($entities[$entity->{$this->idKey}]);
- continue 2;
- }
- }
- elseif ($condition != $entity->{$property_name}) {
- unset($entities[$entity->{$this->idKey}]);
- continue 2;
- }
- }
- }
- }
- return $entities;
- }
- /**
- * Stores entities in the static entity cache.
- *
- * @param $entities
- * Entities to store in the cache.
- */
- protected function cacheSet($entities) {
- $this->entityCache += $entities;
- }
- }
- /**
- * Exception thrown by EntityFieldQuery() on unsupported query syntax.
- *
- * Some storage modules might not support the full range of the syntax for
- * conditions, and will raise an EntityFieldQueryException when an unsupported
- * condition was specified.
- */
- class EntityFieldQueryException extends Exception {}
- /**
- * Retrieves entities matching a given set of conditions.
- *
- * This class allows finding entities based on entity properties (for example,
- * node->changed), field values, and generic entity meta data (bundle,
- * entity type, entity id, and revision ID). It is not possible to query across
- * multiple entity types. For example, there is no facility to find published
- * nodes written by users created in the last hour, as this would require
- * querying both node->status and user->created.
- *
- * Normally we would not want to have public properties on the object, as that
- * allows the object's state to become inconsistent too easily. However, this
- * class's standard use case involves primarily code that does need to have
- * direct access to the collected properties in order to handle alternate
- * execution routines. We therefore use public properties for simplicity. Note
- * that code that is simply creating and running a field query should still use
- * the appropriate methods to add conditions on the query.
- *
- * Storage engines are not required to support every type of query. By default,
- * an EntityFieldQueryException will be raised if an unsupported condition is
- * specified or if the query has field conditions or sorts that are stored in
- * different field storage engines. However, this logic can be overridden in
- * hook_entity_query_alter().
- *
- * Also note that this query does not automatically respect entity access
- * restrictions. Node access control is performed by the SQL storage engine but
- * other storage engines might not do this.
- */
- class EntityFieldQuery {
- /**
- * Indicates that both deleted and non-deleted fields should be returned.
- *
- * @see EntityFieldQuery::deleted()
- */
- const RETURN_ALL = NULL;
- /**
- * TRUE if the query has already been altered, FALSE if it hasn't.
- *
- * Used in alter hooks to check for cloned queries that have already been
- * altered prior to the clone (for example, the pager count query).
- *
- * @var boolean
- */
- public $altered = FALSE;
- /**
- * Associative array of entity-generic metadata conditions.
- *
- * @var array
- *
- * @see EntityFieldQuery::entityCondition()
- */
- public $entityConditions = array();
- /**
- * List of field conditions.
- *
- * @var array
- *
- * @see EntityFieldQuery::fieldCondition()
- */
- public $fieldConditions = array();
- /**
- * List of field meta conditions (language and delta).
- *
- * Field conditions operate on columns specified by hook_field_schema(),
- * the meta conditions operate on columns added by the system: delta
- * and language. These can not be mixed with the field conditions because
- * field columns can have any name including delta and language.
- *
- * @var array
- *
- * @see EntityFieldQuery::fieldLanguageCondition()
- * @see EntityFieldQuery::fieldDeltaCondition()
- */
- public $fieldMetaConditions = array();
- /**
- * List of property conditions.
- *
- * @var array
- *
- * @see EntityFieldQuery::propertyCondition()
- */
- public $propertyConditions = array();
- /**
- * List of order clauses.
- *
- * @var array
- */
- public $order = array();
- /**
- * The query range.
- *
- * @var array
- *
- * @see EntityFieldQuery::range()
- */
- public $range = array();
- /**
- * The query pager data.
- *
- * @var array
- *
- * @see EntityFieldQuery::pager()
- */
- public $pager = array();
- /**
- * Query behavior for deleted data.
- *
- * TRUE to return only deleted data, FALSE to return only non-deleted data,
- * EntityFieldQuery::RETURN_ALL to return everything.
- *
- * @see EntityFieldQuery::deleted()
- */
- public $deleted = FALSE;
- /**
- * A list of field arrays used.
- *
- * Field names passed to EntityFieldQuery::fieldCondition() and
- * EntityFieldQuery::fieldOrderBy() are run through field_info_field() before
- * stored in this array. This way, the elements of this array are field
- * arrays.
- *
- * @var array
- */
- public $fields = array();
- /**
- * TRUE if this is a count query, FALSE if it isn't.
- *
- * @var boolean
- */
- public $count = FALSE;
- /**
- * Flag indicating whether this is querying current or all revisions.
- *
- * @var int
- *
- * @see EntityFieldQuery::age()
- */
- public $age = FIELD_LOAD_CURRENT;
- /**
- * A list of the tags added to this query.
- *
- * @var array
- *
- * @see EntityFieldQuery::addTag()
- */
- public $tags = array();
- /**
- * A list of metadata added to this query.
- *
- * @var array
- *
- * @see EntityFieldQuery::addMetaData()
- */
- public $metaData = array();
- /**
- * The ordered results.
- *
- * @var array
- *
- * @see EntityFieldQuery::execute().
- */
- public $orderedResults = array();
- /**
- * The method executing the query, if it is overriding the default.
- *
- * @var string
- *
- * @see EntityFieldQuery::execute().
- */
- public $executeCallback = '';
- /**
- * Adds a condition on entity-generic metadata.
- *
- * If the overall query contains only entity conditions or ordering, or if
- * there are property conditions, then specifying the entity type is
- * mandatory. If there are field conditions or ordering but no property
- * conditions or ordering, then specifying an entity type is optional. While
- * the field storage engine might support field conditions on more than one
- * entity type, there is no way to query across multiple entity base tables by
- * default. To specify the entity type, pass in 'entity_type' for $name,
- * the type as a string for $value, and no $operator (it's disregarded).
- *
- * 'bundle', 'revision_id' and 'entity_id' have no such restrictions.
- *
- * Note: The "comment" entity type does not support bundle conditions.
- *
- * @param $name
- * 'entity_type', 'bundle', 'revision_id' or 'entity_id'.
- * @param $value
- * The value for $name. 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': 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.
- * The operator can be omitted, and will default to 'IN' if the value is an
- * array, or to '=' otherwise.
- *
- * @return EntityFieldQuery
- * The called object.
- */
- public function entityCondition($name, $value, $operator = NULL) {
- // The '!=' operator is deprecated in favour of the '<>' operator since the
- // latter is ANSI SQL compatible.
- if ($operator == '!=') {
- $operator = '<>';
- }
- $this->entityConditions[$name] = array(
- 'value' => $value,
- 'operator' => $operator,
- );
- return $this;
- }
- /**
- * Adds a condition on field values.
- *
- * Note that entities with empty field values will be excluded from the
- * EntityFieldQuery results when using this method.
- *
- * @param $field
- * Either a field name or a field array.
- * @param $column
- * The column that should hold the value to be matched.
- * @param $value
- * The value to test the column value against.
- * @param $operator
- * The operator to be used to test the given value.
- * @param $delta_group
- * An arbitrary identifier: conditions in the same group must have the same
- * $delta_group.
- * @param $language_group
- * An arbitrary identifier: conditions in the same group must have the same
- * $language_group.
- *
- * @return EntityFieldQuery
- * The called object.
- *
- * @see EntityFieldQuery::addFieldCondition
- * @see EntityFieldQuery::deleted
- */
- public function fieldCondition($field, $column = NULL, $value = NULL, $operator = NULL, $delta_group = NULL, $language_group = NULL) {
- return $this->addFieldCondition($this->fieldConditions, $field, $column, $value, $operator, $delta_group, $language_group);
- }
- /**
- * Adds a condition on the field language column.
- *
- * @param $field
- * Either a field name or a field array.
- * @param $value
- * The value to test the column value against.
- * @param $operator
- * The operator to be used to test the given value.
- * @param $delta_group
- * An arbitrary identifier: conditions in the same group must have the same
- * $delta_group.
- * @param $language_group
- * An arbitrary identifier: conditions in the same group must have the same
- * $language_group.
- *
- * @return EntityFieldQuery
- * The called object.
- *
- * @see EntityFieldQuery::addFieldCondition
- * @see EntityFieldQuery::deleted
- */
- public function fieldLanguageCondition($field, $value = NULL, $operator = NULL, $delta_group = NULL, $language_group = NULL) {
- return $this->addFieldCondition($this->fieldMetaConditions, $field, 'language', $value, $operator, $delta_group, $language_group);
- }
- /**
- * Adds a condition on the field delta column.
- *
- * @param $field
- * Either a field name or a field array.
- * @param $value
- * The value to test the column value against.
- * @param $operator
- * The operator to be used to test the given value.
- * @param $delta_group
- * An arbitrary identifier: conditions in the same group must have the same
- * $delta_group.
- * @param $language_group
- * An arbitrary identifier: conditions in the same group must have the same
- * $language_group.
- *
- * @return EntityFieldQuery
- * The called object.
- *
- * @see EntityFieldQuery::addFieldCondition
- * @see EntityFieldQuery::deleted
- */
- public function fieldDeltaCondition($field, $value = NULL, $operator = NULL, $delta_group = NULL, $language_group = NULL) {
- return $this->addFieldCondition($this->fieldMetaConditions, $field, 'delta', $value, $operator, $delta_group, $language_group);
- }
- /**
- * Adds the given condition to the proper condition array.
- *
- * @param $conditions
- * A reference to an array of conditions.
- * @param $field
- * Either a field name or a field array.
- * @param $column
- * A column defined in the hook_field_schema() of this field. If this is
- * omitted then the query will find only entities that have data in this
- * field, using the entity and property conditions if there are any.
- * @param $value
- * The value to test the column value against. 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': 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.
- * The operator can be omitted, and will default to 'IN' if the value is an
- * array, or to '=' otherwise.
- * @param $delta_group
- * An arbitrary identifier: conditions in the same group must have the same
- * $delta_group. For example, let's presume a multivalue field which has
- * two columns, 'color' and 'shape', and for entity id 1, there are two
- * values: red/square and blue/circle. Entity ID 1 does not have values
- * corresponding to 'red circle', however if you pass 'red' and 'circle' as
- * conditions, it will appear in the results - by default queries will run
- * against any combination of deltas. By passing the conditions with the
- * same $delta_group it will ensure that only values attached to the same
- * delta are matched, and entity 1 would then be excluded from the results.
- * @param $language_group
- * An arbitrary identifier: conditions in the same group must have the same
- * $language_group.
- *
- * @return EntityFieldQuery
- * The called object.
- */
- protected function addFieldCondition(&$conditions, $field, $column = NULL, $value = NULL, $operator = NULL, $delta_group = NULL, $language_group = NULL) {
- // The '!=' operator is deprecated in favour of the '<>' operator since the
- // latter is ANSI SQL compatible.
- if ($operator == '!=') {
- $operator = '<>';
- }
- if (is_scalar($field)) {
- $field_definition = field_info_field($field);
- if (empty($field_definition)) {
- throw new EntityFieldQueryException(t('Unknown field: @field_name', array('@field_name' => $field)));
- }
- $field = $field_definition;
- }
- // Ensure the same index is used for field conditions as for fields.
- $index = count($this->fields);
- $this->fields[$index] = $field;
- if (isset($column)) {
- $conditions[$index] = array(
- 'field' => $field,
- 'column' => $column,
- 'value' => $value,
- 'operator' => $operator,
- 'delta_group' => $delta_group,
- 'language_group' => $language_group,
- );
- }
- return $this;
- }
- /**
- * Adds a condition on an entity-specific property.
- *
- * An $entity_type must be specified by calling
- * EntityFieldCondition::entityCondition('entity_type', $entity_type) before
- * executing the query. Also, by default only entities stored in SQL are
- * supported; however, EntityFieldQuery::executeCallback can be set to handle
- * different entity storage.
- *
- * @param $column
- * A column defined in the hook_schema() of the base table of the entity.
- * @param $value
- * The value to test the field against. 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': 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.
- * The operator can be omitted, and will default to 'IN' if the value is an
- * array, or to '=' otherwise.
- *
- * @return EntityFieldQuery
- * The called object.
- */
- public function propertyCondition($column, $value, $operator = NULL) {
- // The '!=' operator is deprecated in favour of the '<>' operator since the
- // latter is ANSI SQL compatible.
- if ($operator == '!=') {
- $operator = '<>';
- }
- $this->propertyConditions[] = array(
- 'column' => $column,
- 'value' => $value,
- 'operator' => $operator,
- );
- return $this;
- }
- /**
- * Orders the result set by entity-generic metadata.
- *
- * If called multiple times, the query will order by each specified column in
- * the order this method is called.
- *
- * Note: The "comment" and "taxonomy_term" entity types don't support ordering
- * by bundle. For "taxonomy_term", propertyOrderBy('vid') can be used instead.
- *
- * @param $name
- * 'entity_type', 'bundle', 'revision_id' or 'entity_id'.
- * @param $direction
- * The direction to sort. Legal values are "ASC" and "DESC".
- *
- * @return EntityFieldQuery
- * The called object.
- */
- public function entityOrderBy($name, $direction = 'ASC') {
- $this->order[] = array(
- 'type' => 'entity',
- 'specifier' => $name,
- 'direction' => $direction,
- );
- return $this;
- }
- /**
- * Orders the result set by a given field column.
- *
- * If called multiple times, the query will order by each specified column in
- * the order this method is called. Note that entities with empty field
- * values will be excluded from the EntityFieldQuery results when using this
- * method.
- *
- * @param $field
- * Either a field name or a field array.
- * @param $column
- * A column defined in the hook_field_schema() of this field. entity_id and
- * bundle can also be used.
- * @param $direction
- * The direction to sort. Legal values are "ASC" and "DESC".
- *
- * @return EntityFieldQuery
- * The called object.
- */
- public function fieldOrderBy($field, $column, $direction = 'ASC') {
- if (is_scalar($field)) {
- $field_definition = field_info_field($field);
- if (empty($field_definition)) {
- throw new EntityFieldQueryException(t('Unknown field: @field_name', array('@field_name' => $field)));
- }
- $field = $field_definition;
- }
- // Save the index used for the new field, for later use in field storage.
- $index = count($this->fields);
- $this->fields[$index] = $field;
- $this->order[] = array(
- 'type' => 'field',
- 'specifier' => array(
- 'field' => $field,
- 'index' => $index,
- 'column' => $column,
- ),
- 'direction' => $direction,
- );
- return $this;
- }
- /**
- * Orders the result set by an entity-specific property.
- *
- * An $entity_type must be specified by calling
- * EntityFieldCondition::entityCondition('entity_type', $entity_type) before
- * executing the query.
- *
- * If called multiple times, the query will order by each specified column in
- * the order this method is called.
- *
- * @param $column
- * The column on which to order.
- * @param $direction
- * The direction to sort. Legal values are "ASC" and "DESC".
- *
- * @return EntityFieldQuery
- * The called object.
- */
- public function propertyOrderBy($column, $direction = 'ASC') {
- $this->order[] = array(
- 'type' => 'property',
- 'specifier' => $column,
- 'direction' => $direction,
- );
- return $this;
- }
- /**
- * Sets the query to be a count query only.
- *
- * @return EntityFieldQuery
- * The called object.
- */
- public function count() {
- $this->count = TRUE;
- return $this;
- }
- /**
- * Restricts a query to a given range in the result set.
- *
- * @param $start
- * The first entity from the result set to return. If NULL, removes any
- * range directives that are set.
- * @param $length
- * The number of entities to return from the result set.
- *
- * @return EntityFieldQuery
- * The called object.
- */
- public function range($start = NULL, $length = NULL) {
- $this->range = array(
- 'start' => $start,
- 'length' => $length,
- );
- return $this;
- }
- /**
- * 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 EntityFieldQuery
- * The called object.
- */
- public function pager($limit = 10, $element = NULL) {
- if (!isset($element)) {
- $element = PagerDefault::$maxElement++;
- }
- elseif ($element >= PagerDefault::$maxElement) {
- PagerDefault::$maxElement = $element + 1;
- }
- $this->pager = array(
- 'limit' => $limit,
- 'element' => $element,
- );
- return $this;
- }
- /**
- * Enables sortable tables for this query.
- *
- * @param $headers
- * An EFQ Header array based on which the order clause is added to the
- * query.
- *
- * @return EntityFieldQuery
- * The called object.
- */
- public function tableSort(&$headers) {
- // If 'field' is not initialized, the header columns aren't clickable
- foreach ($headers as $key =>$header) {
- if (is_array($header) && isset($header['specifier'])) {
- $headers[$key]['field'] = '';
- }
- }
- $order = tablesort_get_order($headers);
- $direction = tablesort_get_sort($headers);
- foreach ($headers as $header) {
- if (is_array($header) && ($header['data'] == $order['name'])) {
- if ($header['type'] == 'field') {
- $this->fieldOrderBy($header['specifier']['field'], $header['specifier']['column'], $direction);
- }
- else {
- $header['direction'] = $direction;
- $this->order[] = $header;
- }
- }
- }
- return $this;
- }
- /**
- * Filters on the data being deleted.
- *
- * @param $deleted
- * TRUE to only return deleted data, FALSE to return non-deleted data,
- * EntityFieldQuery::RETURN_ALL to return everything. Defaults to FALSE.
- *
- * @return EntityFieldQuery
- * The called object.
- */
- public function deleted($deleted = TRUE) {
- $this->deleted = $deleted;
- return $this;
- }
- /**
- * 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 for all
- * entities. The results will be keyed by entity type and entity ID.
- * - FIELD_LOAD_REVISION: Query all revisions. The results will be keyed by
- * entity type and entity revision ID.
- *
- * @return EntityFieldQuery
- * The called object.
- */
- public function age($age) {
- $this->age = $age;
- return $this;
- }
- /**
- * Adds a tag to the query.
- *
- * Tags are strings that mark a query so that hook_query_alter() and
- * hook_query_TAG_alter() implementations may decide if they wish to alter
- * the query. A query may have any number of tags, and they must be valid PHP
- * identifiers (composed of letters, numbers, and underscores). For example,
- * queries involving nodes that will be displayed for a user need to add the
- * tag 'node_access', so that the node module can add access restrictions to
- * the query.
- *
- * If an entity field query has tags, it must also have an entity type
- * specified, because the alter hook will need the entity base table.
- *
- * @param string $tag
- * The tag to add.
- *
- * @return EntityFieldQuery
- * The called object.
- */
- public function addTag($tag) {
- $this->tags[$tag] = $tag;
- return $this;
- }
- /**
- * Adds additional metadata to the query.
- *
- * Sometimes a query may need to provide additional contextual data for the
- * alter hook. The alter hook implementations may then use that information
- * to decide if and how to take action.
- *
- * @param $key
- * The unique identifier for this piece of metadata. Must be a string that
- * follows the same rules as any other PHP identifier.
- * @param $object
- * The additional data to add to the query. May be any valid PHP variable.
- *
- * @return EntityFieldQuery
- * The called object.
- */
- public function addMetaData($key, $object) {
- $this->metaData[$key] = $object;
- return $this;
- }
- /**
- * Executes the query.
- *
- * After executing the query, $this->orderedResults will contain a list of
- * the same stub entities in the order returned by the query. This is only
- * relevant if there are multiple entity types in the returned value and
- * a field ordering was requested. In every other case, the returned value
- * contains everything necessary for processing.
- *
- * @return
- * Either a number if count() was called or an array of associative arrays
- * of stub entities. The outer array keys are entity types, and the inner
- * array keys are the relevant ID. (In most cases this will be the entity
- * ID. The only exception is when age=FIELD_LOAD_REVISION is used and field
- * conditions or sorts are present -- in this case, the key will be the
- * revision ID.) The entity type will only exist in the outer array if
- * results were found. The inner array values are always stub entities, as
- * returned by entity_create_stub_entity(). To traverse the returned array:
- * @code
- * foreach ($query->execute() as $entity_type => $entities) {
- * foreach ($entities as $entity_id => $entity) {
- * @endcode
- * Note if the entity type is known, then the following snippet will load
- * the entities found:
- * @code
- * $result = $query->execute();
- * if (!empty($result[$my_type])) {
- * $entities = entity_load($my_type, array_keys($result[$my_type]));
- * }
- * @endcode
- */
- public function execute() {
- // Give a chance to other modules to alter the query.
- drupal_alter('entity_query', $this);
- $this->altered = TRUE;
- // Initialize the pager.
- $this->initializePager();
- // Execute the query using the correct callback.
- $result = call_user_func($this->queryCallback(), $this);
- return $result;
- }
- /**
- * Determines the query callback to use for this entity query.
- *
- * @return
- * A callback that can be used with call_user_func().
- */
- public function queryCallback() {
- // Use the override from $this->executeCallback. It can be set either
- // while building the query, or using hook_entity_query_alter().
- if (function_exists($this->executeCallback)) {
- return $this->executeCallback;
- }
- // If there are no field conditions and sorts, and no execute callback
- // then we default to querying entity tables in SQL.
- if (empty($this->fields)) {
- return array($this, 'propertyQuery');
- }
- // If no override, find the storage engine to be used.
- foreach ($this->fields as $field) {
- if (!isset($storage)) {
- $storage = $field['storage']['module'];
- }
- elseif ($storage != $field['storage']['module']) {
- throw new EntityFieldQueryException(t("Can't handle more than one field storage engine"));
- }
- }
- if ($storage) {
- // Use hook_field_storage_query() from the field storage.
- return $storage . '_field_storage_query';
- }
- else {
- throw new EntityFieldQueryException(t("Field storage engine not found."));
- }
- }
- /**
- * Queries entity tables in SQL for property conditions and sorts.
- *
- * This method is only used if there are no field conditions and sorts.
- *
- * @return
- * See EntityFieldQuery::execute().
- */
- protected function propertyQuery() {
- if (empty($this->entityConditions['entity_type'])) {
- throw new EntityFieldQueryException(t('For this query an entity type must be specified.'));
- }
- $entity_type = $this->entityConditions['entity_type']['value'];
- $entity_info = entity_get_info($entity_type);
- if (empty($entity_info['base table'])) {
- throw new EntityFieldQueryException(t('Entity %entity has no base table.', array('%entity' => $entity_type)));
- }
- $base_table = $entity_info['base table'];
- $base_table_schema = drupal_get_schema($base_table);
- $select_query = db_select($base_table);
- $select_query->addExpression(':entity_type', 'entity_type', array(':entity_type' => $entity_type));
- // Process the property conditions.
- foreach ($this->propertyConditions as $property_condition) {
- $this->addCondition($select_query, $base_table . '.' . $property_condition['column'], $property_condition);
- }
- // Process the four possible entity condition.
- // The id field is always present in entity keys.
- $sql_field = $entity_info['entity keys']['id'];
- $id_map['entity_id'] = $sql_field;
- $select_query->addField($base_table, $sql_field, 'entity_id');
- if (isset($this->entityConditions['entity_id'])) {
- $this->addCondition($select_query, $base_table . '.' . $sql_field, $this->entityConditions['entity_id']);
- }
- // If there is a revision key defined, use it.
- if (!empty($entity_info['entity keys']['revision'])) {
- $sql_field = $entity_info['entity keys']['revision'];
- $select_query->addField($base_table, $sql_field, 'revision_id');
- if (isset($this->entityConditions['revision_id'])) {
- $this->addCondition($select_query, $base_table . '.' . $sql_field, $this->entityConditions['revision_id']);
- }
- }
- else {
- $sql_field = 'revision_id';
- $select_query->addExpression('NULL', 'revision_id');
- }
- $id_map['revision_id'] = $sql_field;
- // Handle bundles.
- if (!empty($entity_info['entity keys']['bundle'])) {
- $sql_field = $entity_info['entity keys']['bundle'];
- $having = FALSE;
- if (!empty($base_table_schema['fields'][$sql_field])) {
- $select_query->addField($base_table, $sql_field, 'bundle');
- }
- }
- else {
- $sql_field = 'bundle';
- $select_query->addExpression(':bundle', 'bundle', array(':bundle' => $entity_type));
- $having = TRUE;
- }
- $id_map['bundle'] = $sql_field;
- if (isset($this->entityConditions['bundle'])) {
- if (!empty($entity_info['entity keys']['bundle'])) {
- $this->addCondition($select_query, $base_table . '.' . $sql_field, $this->entityConditions['bundle'], $having);
- }
- else {
- // This entity has no bundle, so invalidate the query.
- $select_query->where('1 = 0');
- }
- }
- // Order the query.
- foreach ($this->order as $order) {
- if ($order['type'] == 'entity') {
- $key = $order['specifier'];
- if (!isset($id_map[$key])) {
- throw new EntityFieldQueryException(t('Do not know how to order on @key for @entity_type', array('@key' => $key, '@entity_type' => $entity_type)));
- }
- $select_query->orderBy($id_map[$key], $order['direction']);
- }
- elseif ($order['type'] == 'property') {
- $select_query->orderBy($base_table . '.' . $order['specifier'], $order['direction']);
- }
- }
- return $this->finishQuery($select_query);
- }
- /**
- * Gets the total number of results and initializes a pager for the query.
- *
- * The pager can be disabled by either setting the pager limit to 0, or by
- * setting this query to be a count query.
- */
- function initializePager() {
- if ($this->pager && !empty($this->pager['limit']) && !$this->count) {
- $page = pager_find_page($this->pager['element']);
- $count_query = clone $this;
- $this->pager['total'] = $count_query->count()->execute();
- $this->pager['start'] = $page * $this->pager['limit'];
- pager_default_initialize($this->pager['total'], $this->pager['limit'], $this->pager['element']);
- $this->range($this->pager['start'], $this->pager['limit']);
- }
- }
- /**
- * Finishes the query.
- *
- * Adds tags, metaData, range and returns the requested list or count.
- *
- * @param SelectQuery $select_query
- * A SelectQuery which has entity_type, entity_id, revision_id and bundle
- * fields added.
- * @param $id_key
- * Which field's values to use as the returned array keys.
- *
- * @return
- * See EntityFieldQuery::execute().
- */
- function finishQuery($select_query, $id_key = 'entity_id') {
- foreach ($this->tags as $tag) {
- $select_query->addTag($tag);
- }
- foreach ($this->metaData as $key => $object) {
- $select_query->addMetaData($key, $object);
- }
- $select_query->addMetaData('entity_field_query', $this);
- if ($this->range) {
- $select_query->range($this->range['start'], $this->range['length']);
- }
- if ($this->count) {
- return $select_query->countQuery()->execute()->fetchField();
- }
- $return = array();
- foreach ($select_query->execute() as $partial_entity) {
- $bundle = isset($partial_entity->bundle) ? $partial_entity->bundle : NULL;
- $entity = entity_create_stub_entity($partial_entity->entity_type, array($partial_entity->entity_id, $partial_entity->revision_id, $bundle));
- $return[$partial_entity->entity_type][$partial_entity->$id_key] = $entity;
- $this->ordered_results[] = $partial_entity;
- }
- return $return;
- }
- /**
- * Adds a condition to an already built SelectQuery (internal function).
- *
- * This is a helper for hook_entity_query() and hook_field_storage_query().
- *
- * @param SelectQuery $select_query
- * A SelectQuery object.
- * @param $sql_field
- * The name of the field.
- * @param $condition
- * A condition as described in EntityFieldQuery::fieldCondition() and
- * EntityFieldQuery::entityCondition().
- * @param $having
- * HAVING or WHERE. This is necessary because SQL can't handle WHERE
- * conditions on aliased columns.
- */
- public function addCondition(SelectQuery $select_query, $sql_field, $condition, $having = FALSE) {
- $method = $having ? 'havingCondition' : 'condition';
- $like_prefix = '';
- switch ($condition['operator']) {
- case 'CONTAINS':
- $like_prefix = '%';
- case 'STARTS_WITH':
- $select_query->$method($sql_field, $like_prefix . db_like($condition['value']) . '%', 'LIKE');
- break;
- default:
- $select_query->$method($sql_field, $condition['value'], $condition['operator']);
- }
- }
- }
- /**
- * Defines an exception thrown when a malformed entity is passed.
- */
- class EntityMalformedException extends Exception { }
|