Projet

Général

Profil

Paste
Télécharger (47,1 ko) Statistiques
| Branche: | Révision:

root / drupal7 / includes / entity.inc @ db2d93dd

1
<?php
2

    
3
/**
4
 * Interface for entity controller classes.
5
 *
6
 * All entity controller classes specified via the 'controller class' key
7
 * returned by hook_entity_info() or hook_entity_info_alter() have to implement
8
 * this interface.
9
 *
10
 * Most simple, SQL-based entity controllers will do better by extending
11
 * DrupalDefaultEntityController instead of implementing this interface
12
 * directly.
13
 */
14
interface DrupalEntityControllerInterface {
15

    
16
  /**
17
   * Resets the internal, static entity cache.
18
   *
19
   * @param $ids
20
   *   (optional) If specified, the cache is reset for the entities with the
21
   *   given ids only.
22
   */
23
  public function resetCache(array $ids = NULL);
24

    
25
  /**
26
   * Loads one or more entities.
27
   *
28
   * @param $ids
29
   *   An array of entity IDs, or FALSE to load all entities.
30
   * @param $conditions
31
   *   An array of conditions. Keys are field names on the entity's base table.
32
   *   Values will be compared for equality. All the comparisons will be ANDed
33
   *   together. This parameter is deprecated; use an EntityFieldQuery instead.
34
   *
35
   * @return
36
   *   An array of entity objects indexed by their ids. When no results are
37
   *   found, an empty array is returned.
38
   */
39
  public function load($ids = array(), $conditions = array());
40
}
41

    
42
/**
43
 * Default implementation of DrupalEntityControllerInterface.
44
 *
45
 * This class can be used as-is by most simple entity types. Entity types
46
 * requiring special handling can extend the class.
47
 */
48
class DrupalDefaultEntityController implements DrupalEntityControllerInterface {
49

    
50
  /**
51
   * Static cache of entities, keyed by entity ID.
52
   *
53
   * @var array
54
   */
55
  protected $entityCache;
56

    
57
  /**
58
   * Entity type for this controller instance.
59
   *
60
   * @var string
61
   */
62
  protected $entityType;
63

    
64
  /**
65
   * Array of information about the entity.
66
   *
67
   * @var array
68
   *
69
   * @see entity_get_info()
70
   */
71
  protected $entityInfo;
72

    
73
  /**
74
   * Additional arguments to pass to hook_TYPE_load().
75
   *
76
   * Set before calling DrupalDefaultEntityController::attachLoad().
77
   *
78
   * @var array
79
   */
80
  protected $hookLoadArguments;
81

    
82
  /**
83
   * Name of the entity's ID field in the entity database table.
84
   *
85
   * @var string
86
   */
87
  protected $idKey;
88

    
89
  /**
90
   * Name of entity's revision database table field, if it supports revisions.
91
   *
92
   * Has the value FALSE if this entity does not use revisions.
93
   *
94
   * @var string
95
   */
96
  protected $revisionKey;
97

    
98
  /**
99
   * The table that stores revisions, if the entity supports revisions.
100
   *
101
   * @var string
102
   */
103
  protected $revisionTable;
104

    
105
  /**
106
   * Whether this entity type should use the static cache.
107
   *
108
   * Set by entity info.
109
   *
110
   * @var boolean
111
   */
112
  protected $cache;
113

    
114
  /**
115
   * Constructor: sets basic variables.
116
   *
117
   * @param $entityType
118
   *   The entity type for which the instance is created.
119
   */
120
  public function __construct($entityType) {
121
    $this->entityType = $entityType;
122
    $this->entityInfo = entity_get_info($entityType);
123
    $this->entityCache = array();
124
    $this->hookLoadArguments = array();
125
    $this->idKey = $this->entityInfo['entity keys']['id'];
126

    
127
    // Check if the entity type supports revisions.
128
    if (!empty($this->entityInfo['entity keys']['revision'])) {
129
      $this->revisionKey = $this->entityInfo['entity keys']['revision'];
130
      $this->revisionTable = $this->entityInfo['revision table'];
131
    }
132
    else {
133
      $this->revisionKey = FALSE;
134
    }
135

    
136
    // Check if the entity type supports static caching of loaded entities.
137
    $this->cache = !empty($this->entityInfo['static cache']);
138
  }
139

    
140
  /**
141
   * Implements DrupalEntityControllerInterface::resetCache().
142
   */
143
  public function resetCache(array $ids = NULL) {
144
    if (isset($ids)) {
145
      foreach ($ids as $id) {
146
        unset($this->entityCache[$id]);
147
      }
148
    }
149
    else {
150
      $this->entityCache = array();
151
    }
152
  }
153

    
154
  /**
155
   * Implements DrupalEntityControllerInterface::load().
156
   */
157
  public function load($ids = array(), $conditions = array()) {
158
    $entities = array();
159

    
160
    // Revisions are not statically cached, and require a different query to
161
    // other conditions, so separate the revision id into its own variable.
162
    if ($this->revisionKey && isset($conditions[$this->revisionKey])) {
163
      $revision_id = $conditions[$this->revisionKey];
164
      unset($conditions[$this->revisionKey]);
165
    }
166
    else {
167
      $revision_id = FALSE;
168
    }
169

    
170
    // Create a new variable which is either a prepared version of the $ids
171
    // array for later comparison with the entity cache, or FALSE if no $ids
172
    // were passed. The $ids array is reduced as items are loaded from cache,
173
    // and we need to know if it's empty for this reason to avoid querying the
174
    // database when all requested entities are loaded from cache.
175
    $passed_ids = !empty($ids) ? array_flip($ids) : FALSE;
176
    // Try to load entities from the static cache, if the entity type supports
177
    // static caching.
178
    if ($this->cache && !$revision_id) {
179
      $entities += $this->cacheGet($ids, $conditions);
180
      // If any entities were loaded, remove them from the ids still to load.
181
      if ($passed_ids) {
182
        $ids = array_keys(array_diff_key($passed_ids, $entities));
183
      }
184
    }
185

    
186
    // Ensure integer entity IDs are valid.
187
    if (!empty($ids)) {
188
      $this->cleanIds($ids);
189
    }
190

    
191
    // Load any remaining entities from the database. This is the case if $ids
192
    // is set to FALSE (so we load all entities), if there are any ids left to
193
    // load, if loading a revision, or if $conditions was passed without $ids.
194
    if ($ids === FALSE || $ids || $revision_id || ($conditions && !$passed_ids)) {
195
      // Build the query.
196
      $query = $this->buildQuery($ids, $conditions, $revision_id);
197
      $queried_entities = $query
198
        ->execute()
199
        ->fetchAllAssoc($this->idKey);
200
    }
201

    
202
    // Pass all entities loaded from the database through $this->attachLoad(),
203
    // which attaches fields (if supported by the entity type) and calls the
204
    // entity type specific load callback, for example hook_node_load().
205
    if (!empty($queried_entities)) {
206
      $this->attachLoad($queried_entities, $revision_id);
207
      $entities += $queried_entities;
208
    }
209

    
210
    if ($this->cache) {
211
      // Add entities to the cache if we are not loading a revision.
212
      if (!empty($queried_entities) && !$revision_id) {
213
        $this->cacheSet($queried_entities);
214
      }
215
    }
216

    
217
    // Ensure that the returned array is ordered the same as the original
218
    // $ids array if this was passed in and remove any invalid ids.
219
    if ($passed_ids) {
220
      // Remove any invalid ids from the array.
221
      $passed_ids = array_intersect_key($passed_ids, $entities);
222
      foreach ($entities as $entity) {
223
        $passed_ids[$entity->{$this->idKey}] = $entity;
224
      }
225
      $entities = $passed_ids;
226
    }
227

    
228
    return $entities;
229
  }
230

    
231
  /**
232
   * Ensures integer entity IDs are valid.
233
   *
234
   * The identifier sanitization provided by this method has been introduced
235
   * as Drupal used to rely on the database to facilitate this, which worked
236
   * correctly with MySQL but led to errors with other DBMS such as PostgreSQL.
237
   *
238
   * @param array $ids
239
   *   The entity IDs to verify. Non-integer IDs are removed from this array if
240
   *   the entity type requires IDs to be integers.
241
   */
242
  protected function cleanIds(&$ids) {
243
    $entity_info = entity_get_info($this->entityType);
244
    if (isset($entity_info['base table field types'])) {
245
      $id_type = $entity_info['base table field types'][$this->idKey];
246
      if ($id_type == 'serial' || $id_type == 'int') {
247
        $ids = array_filter($ids, array($this, 'filterId'));
248
        $ids = array_map('intval', $ids);
249
      }
250
    }
251
  }
252

    
253
  /**
254
   * Callback for array_filter that removes non-integer IDs.
255
   */
256
  protected function filterId($id) {
257
    return is_numeric($id) && $id == (int) $id;
258
  }
259

    
260
  /**
261
   * Builds the query to load the entity.
262
   *
263
   * This has full revision support. For entities requiring special queries,
264
   * the class can be extended, and the default query can be constructed by
265
   * calling parent::buildQuery(). This is usually necessary when the object
266
   * being loaded needs to be augmented with additional data from another
267
   * table, such as loading node type into comments or vocabulary machine name
268
   * into terms, however it can also support $conditions on different tables.
269
   * See CommentController::buildQuery() or TaxonomyTermController::buildQuery()
270
   * for examples.
271
   *
272
   * @param $ids
273
   *   An array of entity IDs, or FALSE to load all entities.
274
   * @param $conditions
275
   *   An array of conditions. Keys are field names on the entity's base table.
276
   *   Values will be compared for equality. All the comparisons will be ANDed
277
   *   together. This parameter is deprecated; use an EntityFieldQuery instead.
278
   * @param $revision_id
279
   *   The ID of the revision to load, or FALSE if this query is asking for the
280
   *   most current revision(s).
281
   *
282
   * @return SelectQuery
283
   *   A SelectQuery object for loading the entity.
284
   */
285
  protected function buildQuery($ids, $conditions = array(), $revision_id = FALSE) {
286
    $query = db_select($this->entityInfo['base table'], 'base');
287

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

    
290
    if ($revision_id) {
291
      $query->join($this->revisionTable, 'revision', "revision.{$this->idKey} = base.{$this->idKey} AND revision.{$this->revisionKey} = :revisionId", array(':revisionId' => $revision_id));
292
    }
293
    elseif ($this->revisionKey) {
294
      $query->join($this->revisionTable, 'revision', "revision.{$this->revisionKey} = base.{$this->revisionKey}");
295
    }
296

    
297
    // Add fields from the {entity} table.
298
    $entity_fields = $this->entityInfo['schema_fields_sql']['base table'];
299

    
300
    if ($this->revisionKey) {
301
      // Add all fields from the {entity_revision} table.
302
      $entity_revision_fields = drupal_map_assoc($this->entityInfo['schema_fields_sql']['revision table']);
303
      // The id field is provided by entity, so remove it.
304
      unset($entity_revision_fields[$this->idKey]);
305

    
306
      // Remove all fields from the base table that are also fields by the same
307
      // name in the revision table.
308
      $entity_field_keys = array_flip($entity_fields);
309
      foreach ($entity_revision_fields as $key => $name) {
310
        if (isset($entity_field_keys[$name])) {
311
          unset($entity_fields[$entity_field_keys[$name]]);
312
        }
313
      }
314
      $query->fields('revision', $entity_revision_fields);
315
    }
316

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

    
319
    if ($ids) {
320
      $query->condition("base.{$this->idKey}", $ids, 'IN');
321
    }
322
    if ($conditions) {
323
      foreach ($conditions as $field => $value) {
324
        $query->condition('base.' . $field, $value);
325
      }
326
    }
327
    return $query;
328
  }
329

    
330
  /**
331
   * Attaches data to entities upon loading.
332
   *
333
   * This will attach fields, if the entity is fieldable. It calls
334
   * hook_entity_load() for modules which need to add data to all entities.
335
   * It also calls hook_TYPE_load() on the loaded entities. For example
336
   * hook_node_load() or hook_user_load(). If your hook_TYPE_load()
337
   * expects special parameters apart from the queried entities, you can set
338
   * $this->hookLoadArguments prior to calling the method.
339
   * See NodeController::attachLoad() for an example.
340
   *
341
   * @param $queried_entities
342
   *   Associative array of query results, keyed on the entity ID.
343
   * @param $revision_id
344
   *   ID of the revision that was loaded, or FALSE if the most current revision
345
   *   was loaded.
346
   */
347
  protected function attachLoad(&$queried_entities, $revision_id = FALSE) {
348
    // Attach fields.
349
    if ($this->entityInfo['fieldable']) {
350
      if ($revision_id) {
351
        field_attach_load_revision($this->entityType, $queried_entities);
352
      }
353
      else {
354
        field_attach_load($this->entityType, $queried_entities);
355
      }
356
    }
357

    
358
    // Call hook_entity_load().
359
    foreach (module_implements('entity_load') as $module) {
360
      $function = $module . '_entity_load';
361
      $function($queried_entities, $this->entityType);
362
    }
363
    // Call hook_TYPE_load(). The first argument for hook_TYPE_load() are
364
    // always the queried entities, followed by additional arguments set in
365
    // $this->hookLoadArguments.
366
    $args = array_merge(array($queried_entities), $this->hookLoadArguments);
367
    foreach (module_implements($this->entityInfo['load hook']) as $module) {
368
      call_user_func_array($module . '_' . $this->entityInfo['load hook'], $args);
369
    }
370
  }
371

    
372
  /**
373
   * Gets entities from the static cache.
374
   *
375
   * @param $ids
376
   *   If not empty, return entities that match these IDs.
377
   * @param $conditions
378
   *   If set, return entities that match all of these conditions.
379
   *
380
   * @return
381
   *   Array of entities from the entity cache.
382
   */
383
  protected function cacheGet($ids, $conditions = array()) {
384
    $entities = array();
385
    // Load any available entities from the internal cache.
386
    if (!empty($this->entityCache)) {
387
      if ($ids) {
388
        $entities += array_intersect_key($this->entityCache, array_flip($ids));
389
      }
390
      // If loading entities only by conditions, fetch all available entities
391
      // from the cache. Entities which don't match are removed later.
392
      elseif ($conditions) {
393
        $entities = $this->entityCache;
394
      }
395
    }
396

    
397
    // Exclude any entities loaded from cache if they don't match $conditions.
398
    // This ensures the same behavior whether loading from memory or database.
399
    if ($conditions) {
400
      foreach ($entities as $entity) {
401
        // Iterate over all conditions and compare them to the entity
402
        // properties. We cannot use array_diff_assoc() here since the
403
        // conditions can be nested arrays, too.
404
        foreach ($conditions as $property_name => $condition) {
405
          if (is_array($condition)) {
406
            // Multiple condition values for one property are treated as OR
407
            // operation: only if the value is not at all in the condition array
408
            // we remove the entity.
409
            if (!in_array($entity->{$property_name}, $condition)) {
410
              unset($entities[$entity->{$this->idKey}]);
411
              continue 2;
412
            }
413
          }
414
          elseif ($condition != $entity->{$property_name}) {
415
            unset($entities[$entity->{$this->idKey}]);
416
            continue 2;
417
          }
418
        }
419
      }
420
    }
421
    return $entities;
422
  }
423

    
424
  /**
425
   * Stores entities in the static entity cache.
426
   *
427
   * @param $entities
428
   *   Entities to store in the cache.
429
   */
430
  protected function cacheSet($entities) {
431
    $this->entityCache += $entities;
432
  }
433
}
434

    
435
/**
436
 * Exception thrown by EntityFieldQuery() on unsupported query syntax.
437
 *
438
 * Some storage modules might not support the full range of the syntax for
439
 * conditions, and will raise an EntityFieldQueryException when an unsupported
440
 * condition was specified.
441
 */
442
class EntityFieldQueryException extends Exception {}
443

    
444
/**
445
 * Retrieves entities matching a given set of conditions.
446
 *
447
 * This class allows finding entities based on entity properties (for example,
448
 * node->changed), field values, and generic entity meta data (bundle,
449
 * entity type, entity id, and revision ID). It is not possible to query across
450
 * multiple entity types. For example, there is no facility to find published
451
 * nodes written by users created in the last hour, as this would require
452
 * querying both node->status and user->created.
453
 *
454
 * Normally we would not want to have public properties on the object, as that
455
 * allows the object's state to become inconsistent too easily. However, this
456
 * class's standard use case involves primarily code that does need to have
457
 * direct access to the collected properties in order to handle alternate
458
 * execution routines. We therefore use public properties for simplicity. Note
459
 * that code that is simply creating and running a field query should still use
460
 * the appropriate methods to add conditions on the query.
461
 *
462
 * Storage engines are not required to support every type of query. By default,
463
 * an EntityFieldQueryException will be raised if an unsupported condition is
464
 * specified or if the query has field conditions or sorts that are stored in
465
 * different field storage engines. However, this logic can be overridden in
466
 * hook_entity_query_alter().
467
 *
468
 * Also note that this query does not automatically respect entity access
469
 * restrictions. Node access control is performed by the SQL storage engine but
470
 * other storage engines might not do this.
471
 */
472
class EntityFieldQuery {
473

    
474
  /**
475
   * Indicates that both deleted and non-deleted fields should be returned.
476
   *
477
   * @see EntityFieldQuery::deleted()
478
   */
479
  const RETURN_ALL = NULL;
480

    
481
  /**
482
   * TRUE if the query has already been altered, FALSE if it hasn't.
483
   *
484
   * Used in alter hooks to check for cloned queries that have already been
485
   * altered prior to the clone (for example, the pager count query).
486
   *
487
   * @var boolean
488
   */
489
  public $altered = FALSE;
490

    
491
  /**
492
   * Associative array of entity-generic metadata conditions.
493
   *
494
   * @var array
495
   *
496
   * @see EntityFieldQuery::entityCondition()
497
   */
498
  public $entityConditions = array();
499

    
500
  /**
501
   * List of field conditions.
502
   *
503
   * @var array
504
   *
505
   * @see EntityFieldQuery::fieldCondition()
506
   */
507
  public $fieldConditions = array();
508

    
509
  /**
510
   * List of field meta conditions (language and delta).
511
   *
512
   * Field conditions operate on columns specified by hook_field_schema(),
513
   * the meta conditions operate on columns added by the system: delta
514
   * and language. These can not be mixed with the field conditions because
515
   * field columns can have any name including delta and language.
516
   *
517
   * @var array
518
   *
519
   * @see EntityFieldQuery::fieldLanguageCondition()
520
   * @see EntityFieldQuery::fieldDeltaCondition()
521
   */
522
  public $fieldMetaConditions = array();
523

    
524
  /**
525
   * List of property conditions.
526
   *
527
   * @var array
528
   *
529
   * @see EntityFieldQuery::propertyCondition()
530
   */
531
  public $propertyConditions = array();
532

    
533
  /**
534
   * List of order clauses.
535
   *
536
   * @var array
537
   */
538
  public $order = array();
539

    
540
  /**
541
   * The query range.
542
   *
543
   * @var array
544
   *
545
   * @see EntityFieldQuery::range()
546
   */
547
  public $range = array();
548

    
549
  /**
550
   * The query pager data.
551
   *
552
   * @var array
553
   *
554
   * @see EntityFieldQuery::pager()
555
   */
556
  public $pager = array();
557

    
558
  /**
559
   * Query behavior for deleted data.
560
   *
561
   * TRUE to return only deleted data, FALSE to return only non-deleted data,
562
   * EntityFieldQuery::RETURN_ALL to return everything.
563
   *
564
   * @see EntityFieldQuery::deleted()
565
   */
566
  public $deleted = FALSE;
567

    
568
  /**
569
   * A list of field arrays used.
570
   *
571
   * Field names passed to EntityFieldQuery::fieldCondition() and
572
   * EntityFieldQuery::fieldOrderBy() are run through field_info_field() before
573
   * stored in this array. This way, the elements of this array are field
574
   * arrays.
575
   *
576
   * @var array
577
   */
578
  public $fields = array();
579

    
580
  /**
581
   * TRUE if this is a count query, FALSE if it isn't.
582
   *
583
   * @var boolean
584
   */
585
  public $count = FALSE;
586

    
587
  /**
588
   * Flag indicating whether this is querying current or all revisions.
589
   *
590
   * @var int
591
   *
592
   * @see EntityFieldQuery::age()
593
   */
594
  public $age = FIELD_LOAD_CURRENT;
595

    
596
  /**
597
   * A list of the tags added to this query.
598
   *
599
   * @var array
600
   *
601
   * @see EntityFieldQuery::addTag()
602
   */
603
  public $tags = array();
604

    
605
  /**
606
   * A list of metadata added to this query.
607
   *
608
   * @var array
609
   *
610
   * @see EntityFieldQuery::addMetaData()
611
   */
612
  public $metaData = array();
613

    
614
  /**
615
   * The ordered results.
616
   *
617
   * @var array
618
   *
619
   * @see EntityFieldQuery::execute().
620
   */
621
  public $orderedResults = array();
622

    
623
  /**
624
   * The method executing the query, if it is overriding the default.
625
   *
626
   * @var string
627
   *
628
   * @see EntityFieldQuery::execute().
629
   */
630
  public $executeCallback = '';
631

    
632
  /**
633
   * Adds a condition on entity-generic metadata.
634
   *
635
   * If the overall query contains only entity conditions or ordering, or if
636
   * there are property conditions, then specifying the entity type is
637
   * mandatory. If there are field conditions or ordering but no property
638
   * conditions or ordering, then specifying an entity type is optional. While
639
   * the field storage engine might support field conditions on more than one
640
   * entity type, there is no way to query across multiple entity base tables by
641
   * default. To specify the entity type, pass in 'entity_type' for $name,
642
   * the type as a string for $value, and no $operator (it's disregarded).
643
   *
644
   * 'bundle', 'revision_id' and 'entity_id' have no such restrictions.
645
   *
646
   * Note: The "comment" entity type does not support bundle conditions.
647
   *
648
   * @param $name
649
   *   'entity_type', 'bundle', 'revision_id' or 'entity_id'.
650
   * @param $value
651
   *   The value for $name. In most cases, this is a scalar. For more complex
652
   *   options, it is an array. The meaning of each element in the array is
653
   *   dependent on $operator.
654
   * @param $operator
655
   *   Possible values:
656
   *   - '=', '<>', '>', '>=', '<', '<=', 'STARTS_WITH', 'CONTAINS': These
657
   *     operators expect $value to be a literal of the same type as the
658
   *     column.
659
   *   - 'IN', 'NOT IN': These operators expect $value to be an array of
660
   *     literals of the same type as the column.
661
   *   - 'BETWEEN': This operator expects $value to be an array of two literals
662
   *     of the same type as the column.
663
   *   The operator can be omitted, and will default to 'IN' if the value is an
664
   *   array, or to '=' otherwise.
665
   *
666
   * @return EntityFieldQuery
667
   *   The called object.
668
   */
669
  public function entityCondition($name, $value, $operator = NULL) {
670
    // The '!=' operator is deprecated in favour of the '<>' operator since the
671
    // latter is ANSI SQL compatible.
672
    if ($operator == '!=') {
673
      $operator = '<>';
674
    }
675
    $this->entityConditions[$name] = array(
676
      'value' => $value,
677
      'operator' => $operator,
678
    );
679
    return $this;
680
  }
681

    
682
  /**
683
   * Adds a condition on field values.
684
   *
685
   * Note that entities with empty field values will be excluded from the
686
   * EntityFieldQuery results when using this method.
687
   *
688
   * @param $field
689
   *   Either a field name or a field array.
690
   * @param $column
691
   *   The column that should hold the value to be matched.
692
   * @param $value
693
   *   The value to test the column value against.
694
   * @param $operator
695
   *   The operator to be used to test the given value.
696
   * @param $delta_group
697
   *   An arbitrary identifier: conditions in the same group must have the same
698
   *   $delta_group.
699
   * @param $language_group
700
   *   An arbitrary identifier: conditions in the same group must have the same
701
   *   $language_group.
702
   *
703
   * @return EntityFieldQuery
704
   *   The called object.
705
   *
706
   * @see EntityFieldQuery::addFieldCondition
707
   * @see EntityFieldQuery::deleted
708
   */
709
  public function fieldCondition($field, $column = NULL, $value = NULL, $operator = NULL, $delta_group = NULL, $language_group = NULL) {
710
    return $this->addFieldCondition($this->fieldConditions, $field, $column, $value, $operator, $delta_group, $language_group);
711
  }
712

    
713
  /**
714
   * Adds a condition on the field language column.
715
   *
716
   * @param $field
717
   *   Either a field name or a field array.
718
   * @param $value
719
   *   The value to test the column value against.
720
   * @param $operator
721
   *   The operator to be used to test the given value.
722
   * @param $delta_group
723
   *   An arbitrary identifier: conditions in the same group must have the same
724
   *   $delta_group.
725
   * @param $language_group
726
   *   An arbitrary identifier: conditions in the same group must have the same
727
   *   $language_group.
728
   *
729
   * @return EntityFieldQuery
730
   *   The called object.
731
   *
732
   * @see EntityFieldQuery::addFieldCondition
733
   * @see EntityFieldQuery::deleted
734
   */
735
  public function fieldLanguageCondition($field, $value = NULL, $operator = NULL, $delta_group = NULL, $language_group = NULL) {
736
    return $this->addFieldCondition($this->fieldMetaConditions, $field, 'language', $value, $operator, $delta_group, $language_group);
737
  }
738

    
739
  /**
740
   * Adds a condition on the field delta column.
741
   *
742
   * @param $field
743
   *   Either a field name or a field array.
744
   * @param $value
745
   *   The value to test the column value against.
746
   * @param $operator
747
   *   The operator to be used to test the given value.
748
   * @param $delta_group
749
   *   An arbitrary identifier: conditions in the same group must have the same
750
   *   $delta_group.
751
   * @param $language_group
752
   *   An arbitrary identifier: conditions in the same group must have the same
753
   *   $language_group.
754
   *
755
   * @return EntityFieldQuery
756
   *   The called object.
757
   *
758
   * @see EntityFieldQuery::addFieldCondition
759
   * @see EntityFieldQuery::deleted
760
   */
761
  public function fieldDeltaCondition($field, $value = NULL, $operator = NULL, $delta_group = NULL, $language_group = NULL) {
762
    return $this->addFieldCondition($this->fieldMetaConditions, $field, 'delta', $value, $operator, $delta_group, $language_group);
763
  }
764

    
765
  /**
766
   * Adds the given condition to the proper condition array.
767
   *
768
   * @param $conditions
769
   *   A reference to an array of conditions.
770
   * @param $field
771
   *   Either a field name or a field array.
772
   * @param $column
773
   *   A column defined in the hook_field_schema() of this field. If this is
774
   *   omitted then the query will find only entities that have data in this
775
   *   field, using the entity and property conditions if there are any.
776
   * @param $value
777
   *   The value to test the column value against. In most cases, this is a
778
   *   scalar. For more complex options, it is an array. The meaning of each
779
   *   element in the array is dependent on $operator.
780
   * @param $operator
781
   *   Possible values:
782
   *   - '=', '<>', '>', '>=', '<', '<=', 'STARTS_WITH', 'CONTAINS': These
783
   *     operators expect $value to be a literal of the same type as the
784
   *     column.
785
   *   - 'IN', 'NOT IN': These operators expect $value to be an array of
786
   *     literals of the same type as the column.
787
   *   - 'BETWEEN': This operator expects $value to be an array of two literals
788
   *     of the same type as the column.
789
   *   The operator can be omitted, and will default to 'IN' if the value is an
790
   *   array, or to '=' otherwise.
791
   * @param $delta_group
792
   *   An arbitrary identifier: conditions in the same group must have the same
793
   *   $delta_group. For example, let's presume a multivalue field which has
794
   *   two columns, 'color' and 'shape', and for entity id 1, there are two
795
   *   values: red/square and blue/circle. Entity ID 1 does not have values
796
   *   corresponding to 'red circle', however if you pass 'red' and 'circle' as
797
   *   conditions, it will appear in the  results - by default queries will run
798
   *   against any combination of deltas. By passing the conditions with the
799
   *   same $delta_group it will ensure that only values attached to the same
800
   *   delta are matched, and entity 1 would then be excluded from the results.
801
   * @param $language_group
802
   *   An arbitrary identifier: conditions in the same group must have the same
803
   *   $language_group.
804
   *
805
   * @return EntityFieldQuery
806
   *   The called object.
807
   */
808
  protected function addFieldCondition(&$conditions, $field, $column = NULL, $value = NULL, $operator = NULL, $delta_group = NULL, $language_group = NULL) {
809
    // The '!=' operator is deprecated in favour of the '<>' operator since the
810
    // latter is ANSI SQL compatible.
811
    if ($operator == '!=') {
812
      $operator = '<>';
813
    }
814
    if (is_scalar($field)) {
815
      $field_definition = field_info_field($field);
816
      if (empty($field_definition)) {
817
        throw new EntityFieldQueryException(t('Unknown field: @field_name', array('@field_name' => $field)));
818
      }
819
      $field = $field_definition;
820
    }
821
    // Ensure the same index is used for field conditions as for fields.
822
    $index = count($this->fields);
823
    $this->fields[$index] = $field;
824
    if (isset($column)) {
825
      $conditions[$index] = array(
826
        'field' => $field,
827
        'column' => $column,
828
        'value' => $value,
829
        'operator' => $operator,
830
        'delta_group' => $delta_group,
831
        'language_group' => $language_group,
832
      );
833
    }
834
    return $this;
835
  }
836

    
837
  /**
838
   * Adds a condition on an entity-specific property.
839
   *
840
   * An $entity_type must be specified by calling
841
   * EntityFieldCondition::entityCondition('entity_type', $entity_type) before
842
   * executing the query. Also, by default only entities stored in SQL are
843
   * supported; however, EntityFieldQuery::executeCallback can be set to handle
844
   * different entity storage.
845
   *
846
   * @param $column
847
   *   A column defined in the hook_schema() of the base table of the entity.
848
   * @param $value
849
   *   The value to test the field against. In most cases, this is a scalar. For
850
   *   more complex options, it is an array. The meaning of each element in the
851
   *   array is dependent on $operator.
852
   * @param $operator
853
   *   Possible values:
854
   *   - '=', '<>', '>', '>=', '<', '<=', 'STARTS_WITH', 'CONTAINS': These
855
   *     operators expect $value to be a literal of the same type as the
856
   *     column.
857
   *   - 'IN', 'NOT IN': These operators expect $value to be an array of
858
   *     literals of the same type as the column.
859
   *   - 'BETWEEN': This operator expects $value to be an array of two literals
860
   *     of the same type as the column.
861
   *   The operator can be omitted, and will default to 'IN' if the value is an
862
   *   array, or to '=' otherwise.
863
   *
864
   * @return EntityFieldQuery
865
   *   The called object.
866
   */
867
  public function propertyCondition($column, $value, $operator = NULL) {
868
    // The '!=' operator is deprecated in favour of the '<>' operator since the
869
    // latter is ANSI SQL compatible.
870
    if ($operator == '!=') {
871
      $operator = '<>';
872
    }
873
    $this->propertyConditions[] = array(
874
      'column' => $column,
875
      'value' => $value,
876
      'operator' => $operator,
877
    );
878
    return $this;
879
  }
880

    
881
  /**
882
   * Orders the result set by entity-generic metadata.
883
   *
884
   * If called multiple times, the query will order by each specified column in
885
   * the order this method is called.
886
   *
887
   * Note: The "comment" and "taxonomy_term" entity types don't support ordering
888
   * by bundle. For "taxonomy_term", propertyOrderBy('vid') can be used instead.
889
   *
890
   * @param $name
891
   *   'entity_type', 'bundle', 'revision_id' or 'entity_id'.
892
   * @param $direction
893
   *   The direction to sort. Legal values are "ASC" and "DESC".
894
   *
895
   * @return EntityFieldQuery
896
   *   The called object.
897
   */
898
  public function entityOrderBy($name, $direction = 'ASC') {
899
    $this->order[] = array(
900
      'type' => 'entity',
901
      'specifier' => $name,
902
      'direction' => $direction,
903
    );
904
    return $this;
905
  }
906

    
907
  /**
908
   * Orders the result set by a given field column.
909
   *
910
   * If called multiple times, the query will order by each specified column in
911
   * the order this method is called. Note that entities with empty field
912
   * values will be excluded from the EntityFieldQuery results when using this
913
   * method.
914
   *
915
   * @param $field
916
   *   Either a field name or a field array.
917
   * @param $column
918
   *   A column defined in the hook_field_schema() of this field. entity_id and
919
   *   bundle can also be used.
920
   * @param $direction
921
   *   The direction to sort. Legal values are "ASC" and "DESC".
922
   *
923
   * @return EntityFieldQuery
924
   *   The called object.
925
   */
926
  public function fieldOrderBy($field, $column, $direction = 'ASC') {
927
    if (is_scalar($field)) {
928
      $field_definition = field_info_field($field);
929
      if (empty($field_definition)) {
930
        throw new EntityFieldQueryException(t('Unknown field: @field_name', array('@field_name' => $field)));
931
      }
932
      $field = $field_definition;
933
    }
934
    // Save the index used for the new field, for later use in field storage.
935
    $index = count($this->fields);
936
    $this->fields[$index] = $field;
937
    $this->order[] = array(
938
      'type' => 'field',
939
      'specifier' => array(
940
        'field' => $field,
941
        'index' => $index,
942
        'column' => $column,
943
      ),
944
      'direction' => $direction,
945
    );
946
    return $this;
947
  }
948

    
949
  /**
950
   * Orders the result set by an entity-specific property.
951
   *
952
   * An $entity_type must be specified by calling
953
   * EntityFieldCondition::entityCondition('entity_type', $entity_type) before
954
   * executing the query.
955
   *
956
   * If called multiple times, the query will order by each specified column in
957
   * the order this method is called.
958
   *
959
   * @param $column
960
   *   The column on which to order.
961
   * @param $direction
962
   *   The direction to sort. Legal values are "ASC" and "DESC".
963
   *
964
   * @return EntityFieldQuery
965
   *   The called object.
966
   */
967
  public function propertyOrderBy($column, $direction = 'ASC') {
968
    $this->order[] = array(
969
      'type' => 'property',
970
      'specifier' => $column,
971
      'direction' => $direction,
972
    );
973
    return $this;
974
  }
975

    
976
  /**
977
   * Sets the query to be a count query only.
978
   *
979
   * @return EntityFieldQuery
980
   *   The called object.
981
   */
982
  public function count() {
983
    $this->count = TRUE;
984
    return $this;
985
  }
986

    
987
  /**
988
   * Restricts a query to a given range in the result set.
989
   *
990
   * @param $start
991
   *   The first entity from the result set to return. If NULL, removes any
992
   *   range directives that are set.
993
   * @param $length
994
   *   The number of entities to return from the result set.
995
   *
996
   * @return EntityFieldQuery
997
   *   The called object.
998
   */
999
  public function range($start = NULL, $length = NULL) {
1000
    $this->range = array(
1001
      'start' => $start,
1002
      'length' => $length,
1003
    );
1004
    return $this;
1005
  }
1006

    
1007
  /**
1008
   * Enables a pager for the query.
1009
   *
1010
   * @param $limit
1011
   *   An integer specifying the number of elements per page.  If passed a false
1012
   *   value (FALSE, 0, NULL), the pager is disabled.
1013
   * @param $element
1014
   *   An optional integer to distinguish between multiple pagers on one page.
1015
   *   If not provided, one is automatically calculated.
1016
   *
1017
   * @return EntityFieldQuery
1018
   *   The called object.
1019
   */
1020
  public function pager($limit = 10, $element = NULL) {
1021
    if (!isset($element)) {
1022
      $element = PagerDefault::$maxElement++;
1023
    }
1024
    elseif ($element >= PagerDefault::$maxElement) {
1025
      PagerDefault::$maxElement = $element + 1;
1026
    }
1027

    
1028
    $this->pager = array(
1029
      'limit' => $limit,
1030
      'element' => $element,
1031
    );
1032
    return $this;
1033
  }
1034

    
1035
  /**
1036
   * Enables sortable tables for this query.
1037
   *
1038
   * @param $headers
1039
   *   An EFQ Header array based on which the order clause is added to the
1040
   *   query.
1041
   *
1042
   * @return EntityFieldQuery
1043
   *   The called object.
1044
   */
1045
  public function tableSort(&$headers) {
1046
    // If 'field' is not initialized, the header columns aren't clickable
1047
    foreach ($headers as $key =>$header) {
1048
      if (is_array($header) && isset($header['specifier'])) {
1049
        $headers[$key]['field'] = '';
1050
      }
1051
    }
1052

    
1053
    $order = tablesort_get_order($headers);
1054
    $direction = tablesort_get_sort($headers);
1055
    foreach ($headers as $header) {
1056
      if (is_array($header) && ($header['data'] == $order['name'])) {
1057
        if ($header['type'] == 'field') {
1058
          $this->fieldOrderBy($header['specifier']['field'], $header['specifier']['column'], $direction);
1059
        }
1060
        else {
1061
          $header['direction'] = $direction;
1062
          $this->order[] = $header;
1063
        }
1064
      }
1065
    }
1066

    
1067
    return $this;
1068
  }
1069

    
1070
  /**
1071
   * Filters on the data being deleted.
1072
   *
1073
   * @param $deleted
1074
   *   TRUE to only return deleted data, FALSE to return non-deleted data,
1075
   *   EntityFieldQuery::RETURN_ALL to return everything. Defaults to FALSE.
1076
   *
1077
   * @return EntityFieldQuery
1078
   *   The called object.
1079
   */
1080
  public function deleted($deleted = TRUE) {
1081
    $this->deleted = $deleted;
1082
    return $this;
1083
  }
1084

    
1085
  /**
1086
   * Queries the current or every revision.
1087
   *
1088
   * Note that this only affects field conditions. Property conditions always
1089
   * apply to the current revision.
1090
   * @TODO: Once revision tables have been cleaned up, revisit this.
1091
   *
1092
   * @param $age
1093
   *   - FIELD_LOAD_CURRENT (default): Query the most recent revisions for all
1094
   *     entities. The results will be keyed by entity type and entity ID.
1095
   *   - FIELD_LOAD_REVISION: Query all revisions. The results will be keyed by
1096
   *     entity type and entity revision ID.
1097
   *
1098
   * @return EntityFieldQuery
1099
   *   The called object.
1100
   */
1101
  public function age($age) {
1102
    $this->age = $age;
1103
    return $this;
1104
  }
1105

    
1106
  /**
1107
   * Adds a tag to the query.
1108
   *
1109
   * Tags are strings that mark a query so that hook_query_alter() and
1110
   * hook_query_TAG_alter() implementations may decide if they wish to alter
1111
   * the query. A query may have any number of tags, and they must be valid PHP
1112
   * identifiers (composed of letters, numbers, and underscores). For example,
1113
   * queries involving nodes that will be displayed for a user need to add the
1114
   * tag 'node_access', so that the node module can add access restrictions to
1115
   * the query.
1116
   *
1117
   * If an entity field query has tags, it must also have an entity type
1118
   * specified, because the alter hook will need the entity base table.
1119
   *
1120
   * @param string $tag
1121
   *   The tag to add.
1122
   *
1123
   * @return EntityFieldQuery
1124
   *   The called object.
1125
   */
1126
  public function addTag($tag) {
1127
    $this->tags[$tag] = $tag;
1128
    return $this;
1129
  }
1130

    
1131
  /**
1132
   * Adds additional metadata to the query.
1133
   *
1134
   * Sometimes a query may need to provide additional contextual data for the
1135
   * alter hook. The alter hook implementations may then use that information
1136
   * to decide if and how to take action.
1137
   *
1138
   * @param $key
1139
   *   The unique identifier for this piece of metadata. Must be a string that
1140
   *   follows the same rules as any other PHP identifier.
1141
   * @param $object
1142
   *   The additional data to add to the query. May be any valid PHP variable.
1143
   *
1144
   * @return EntityFieldQuery
1145
   *   The called object.
1146
   */
1147
  public function addMetaData($key, $object) {
1148
    $this->metaData[$key] = $object;
1149
    return $this;
1150
  }
1151

    
1152
  /**
1153
   * Executes the query.
1154
   *
1155
   * After executing the query, $this->orderedResults will contain a list of
1156
   * the same stub entities in the order returned by the query. This is only
1157
   * relevant if there are multiple entity types in the returned value and
1158
   * a field ordering was requested. In every other case, the returned value
1159
   * contains everything necessary for processing.
1160
   *
1161
   * @return
1162
   *   Either a number if count() was called or an array of associative arrays
1163
   *   of stub entities. The outer array keys are entity types, and the inner
1164
   *   array keys are the relevant ID. (In most cases this will be the entity
1165
   *   ID. The only exception is when age=FIELD_LOAD_REVISION is used and field
1166
   *   conditions or sorts are present -- in this case, the key will be the
1167
   *   revision ID.) The entity type will only exist in the outer array if
1168
   *   results were found. The inner array values are always stub entities, as
1169
   *   returned by entity_create_stub_entity(). To traverse the returned array:
1170
   *   @code
1171
   *     foreach ($query->execute() as $entity_type => $entities) {
1172
   *       foreach ($entities as $entity_id => $entity) {
1173
   *   @endcode
1174
   *   Note if the entity type is known, then the following snippet will load
1175
   *   the entities found:
1176
   *   @code
1177
   *     $result = $query->execute();
1178
   *     if (!empty($result[$my_type])) {
1179
   *       $entities = entity_load($my_type, array_keys($result[$my_type]));
1180
   *     }
1181
   *   @endcode
1182
   */
1183
  public function execute() {
1184
    // Give a chance to other modules to alter the query.
1185
    drupal_alter('entity_query', $this);
1186
    $this->altered = TRUE;
1187

    
1188
    // Initialize the pager.
1189
    $this->initializePager();
1190

    
1191
    // Execute the query using the correct callback.
1192
    $result = call_user_func($this->queryCallback(), $this);
1193

    
1194
    return $result;
1195
  }
1196

    
1197
  /**
1198
   * Determines the query callback to use for this entity query.
1199
   *
1200
   * @return
1201
   *   A callback that can be used with call_user_func().
1202
   */
1203
  public function queryCallback() {
1204
    // Use the override from $this->executeCallback. It can be set either
1205
    // while building the query, or using hook_entity_query_alter().
1206
    if (function_exists($this->executeCallback)) {
1207
      return $this->executeCallback;
1208
    }
1209
    // If there are no field conditions and sorts, and no execute callback
1210
    // then we default to querying entity tables in SQL.
1211
    if (empty($this->fields)) {
1212
      return array($this, 'propertyQuery');
1213
    }
1214
    // If no override, find the storage engine to be used.
1215
    foreach ($this->fields as $field) {
1216
      if (!isset($storage)) {
1217
        $storage = $field['storage']['module'];
1218
      }
1219
      elseif ($storage != $field['storage']['module']) {
1220
        throw new EntityFieldQueryException(t("Can't handle more than one field storage engine"));
1221
      }
1222
    }
1223
    if ($storage) {
1224
      // Use hook_field_storage_query() from the field storage.
1225
      return $storage . '_field_storage_query';
1226
    }
1227
    else {
1228
      throw new EntityFieldQueryException(t("Field storage engine not found."));
1229
    }
1230
  }
1231

    
1232
  /**
1233
   * Queries entity tables in SQL for property conditions and sorts.
1234
   *
1235
   * This method is only used if there are no field conditions and sorts.
1236
   *
1237
   * @return
1238
   *   See EntityFieldQuery::execute().
1239
   */
1240
  protected function propertyQuery() {
1241
    if (empty($this->entityConditions['entity_type'])) {
1242
      throw new EntityFieldQueryException(t('For this query an entity type must be specified.'));
1243
    }
1244
    $entity_type = $this->entityConditions['entity_type']['value'];
1245
    $entity_info = entity_get_info($entity_type);
1246
    if (empty($entity_info['base table'])) {
1247
      throw new EntityFieldQueryException(t('Entity %entity has no base table.', array('%entity' => $entity_type)));
1248
    }
1249
    $base_table = $entity_info['base table'];
1250
    $base_table_schema = drupal_get_schema($base_table);
1251
    $select_query = db_select($base_table);
1252
    $select_query->addExpression(':entity_type', 'entity_type', array(':entity_type' => $entity_type));
1253
    // Process the property conditions.
1254
    foreach ($this->propertyConditions as $property_condition) {
1255
      $this->addCondition($select_query, $base_table . '.' . $property_condition['column'], $property_condition);
1256
    }
1257
    // Process the four possible entity condition.
1258
    // The id field is always present in entity keys.
1259
    $sql_field = $entity_info['entity keys']['id'];
1260
    $id_map['entity_id'] = $sql_field;
1261
    $select_query->addField($base_table, $sql_field, 'entity_id');
1262
    if (isset($this->entityConditions['entity_id'])) {
1263
      $this->addCondition($select_query, $base_table . '.' . $sql_field, $this->entityConditions['entity_id']);
1264
    }
1265

    
1266
    // If there is a revision key defined, use it.
1267
    if (!empty($entity_info['entity keys']['revision'])) {
1268
      $sql_field = $entity_info['entity keys']['revision'];
1269
      $select_query->addField($base_table, $sql_field, 'revision_id');
1270
      if (isset($this->entityConditions['revision_id'])) {
1271
        $this->addCondition($select_query, $base_table . '.' . $sql_field, $this->entityConditions['revision_id']);
1272
      }
1273
    }
1274
    else {
1275
      $sql_field = 'revision_id';
1276
      $select_query->addExpression('NULL', 'revision_id');
1277
    }
1278
    $id_map['revision_id'] = $sql_field;
1279

    
1280
    // Handle bundles.
1281
    if (!empty($entity_info['entity keys']['bundle'])) {
1282
      $sql_field = $entity_info['entity keys']['bundle'];
1283
      $having = FALSE;
1284

    
1285
      if (!empty($base_table_schema['fields'][$sql_field])) {
1286
        $select_query->addField($base_table, $sql_field, 'bundle');
1287
      }
1288
    }
1289
    else {
1290
      $sql_field = 'bundle';
1291
      $select_query->addExpression(':bundle', 'bundle', array(':bundle' => $entity_type));
1292
      $having = TRUE;
1293
    }
1294
    $id_map['bundle'] = $sql_field;
1295
    if (isset($this->entityConditions['bundle'])) {
1296
      if (!empty($entity_info['entity keys']['bundle'])) {
1297
        $this->addCondition($select_query, $base_table . '.' . $sql_field, $this->entityConditions['bundle'], $having);
1298
      }
1299
      else {
1300
        // This entity has no bundle, so invalidate the query.
1301
        $select_query->where('1 = 0');
1302
      }
1303
    }
1304

    
1305
    // Order the query.
1306
    foreach ($this->order as $order) {
1307
      if ($order['type'] == 'entity') {
1308
        $key = $order['specifier'];
1309
        if (!isset($id_map[$key])) {
1310
          throw new EntityFieldQueryException(t('Do not know how to order on @key for @entity_type', array('@key' => $key, '@entity_type' => $entity_type)));
1311
        }
1312
        $select_query->orderBy($id_map[$key], $order['direction']);
1313
      }
1314
      elseif ($order['type'] == 'property') {
1315
        $select_query->orderBy($base_table . '.' . $order['specifier'], $order['direction']);
1316
      }
1317
    }
1318

    
1319
    return $this->finishQuery($select_query);
1320
  }
1321

    
1322
  /**
1323
   * Gets the total number of results and initializes a pager for the query.
1324
   *
1325
   * The pager can be disabled by either setting the pager limit to 0, or by
1326
   * setting this query to be a count query.
1327
   */
1328
  function initializePager() {
1329
    if ($this->pager && !empty($this->pager['limit']) && !$this->count) {
1330
      $page = pager_find_page($this->pager['element']);
1331
      $count_query = clone $this;
1332
      $this->pager['total'] = $count_query->count()->execute();
1333
      $this->pager['start'] = $page * $this->pager['limit'];
1334
      pager_default_initialize($this->pager['total'], $this->pager['limit'], $this->pager['element']);
1335
      $this->range($this->pager['start'], $this->pager['limit']);
1336
    }
1337
  }
1338

    
1339
  /**
1340
   * Finishes the query.
1341
   *
1342
   * Adds tags, metaData, range and returns the requested list or count.
1343
   *
1344
   * @param SelectQuery $select_query
1345
   *   A SelectQuery which has entity_type, entity_id, revision_id and bundle
1346
   *   fields added.
1347
   * @param $id_key
1348
   *   Which field's values to use as the returned array keys.
1349
   *
1350
   * @return
1351
   *   See EntityFieldQuery::execute().
1352
   */
1353
  function finishQuery($select_query, $id_key = 'entity_id') {
1354
    foreach ($this->tags as $tag) {
1355
      $select_query->addTag($tag);
1356
    }
1357
    foreach ($this->metaData as $key => $object) {
1358
      $select_query->addMetaData($key, $object);
1359
    }
1360
    $select_query->addMetaData('entity_field_query', $this);
1361
    if ($this->range) {
1362
      $select_query->range($this->range['start'], $this->range['length']);
1363
    }
1364
    if ($this->count) {
1365
      return $select_query->countQuery()->execute()->fetchField();
1366
    }
1367
    $return = array();
1368
    foreach ($select_query->execute() as $partial_entity) {
1369
      $bundle = isset($partial_entity->bundle) ? $partial_entity->bundle : NULL;
1370
      $entity = entity_create_stub_entity($partial_entity->entity_type, array($partial_entity->entity_id, $partial_entity->revision_id, $bundle));
1371
      $return[$partial_entity->entity_type][$partial_entity->$id_key] = $entity;
1372
      $this->ordered_results[] = $partial_entity;
1373
    }
1374
    return $return;
1375
  }
1376

    
1377
  /**
1378
   * Adds a condition to an already built SelectQuery (internal function).
1379
   *
1380
   * This is a helper for hook_entity_query() and hook_field_storage_query().
1381
   *
1382
   * @param SelectQuery $select_query
1383
   *   A SelectQuery object.
1384
   * @param $sql_field
1385
   *   The name of the field.
1386
   * @param $condition
1387
   *   A condition as described in EntityFieldQuery::fieldCondition() and
1388
   *   EntityFieldQuery::entityCondition().
1389
   * @param $having
1390
   *   HAVING or WHERE. This is necessary because SQL can't handle WHERE
1391
   *   conditions on aliased columns.
1392
   */
1393
  public function addCondition(SelectQuery $select_query, $sql_field, $condition, $having = FALSE) {
1394
    $method = $having ? 'havingCondition' : 'condition';
1395
    $like_prefix = '';
1396
    switch ($condition['operator']) {
1397
      case 'CONTAINS':
1398
        $like_prefix = '%';
1399
      case 'STARTS_WITH':
1400
        $select_query->$method($sql_field, $like_prefix . db_like($condition['value']) . '%', 'LIKE');
1401
        break;
1402
      default:
1403
        $select_query->$method($sql_field, $condition['value'], $condition['operator']);
1404
    }
1405
  }
1406

    
1407
}
1408

    
1409
/**
1410
 * Defines an exception thrown when a malformed entity is passed.
1411
 */
1412
class EntityMalformedException extends Exception { }