Server : Apache
System : Linux copper.netcy.com 2.6.32-754.27.1.el6.centos.plus.x86_64 #1 SMP Thu Jan 30 13:54:25 UTC 2020 x86_64
User : montcaro ( 581)
PHP Version : 7.4.28
Disable Function : NONE
Directory : /home/montcaro/public_html/includes/
|
Server : Apache System : Linux copper.netcy.com 2.6.32-754.27.1.el6.centos.plus.x86_64 #1 SMP Thu Jan 30 13:54:25 UTC 2020 x86_64 User : montcaro ( 581) PHP Version : 7.4.28 Disable Function : NONE Directory : /home/montcaro/public_html/includes/ |
<?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 { }