function entity_load

7 common.inc entity_load($entity_type, $ids = FALSE, $conditions = array(), $reset = FALSE)
8 entity.inc entity_load($entity_type, $id, $reset = FALSE)

Load entities from the database.

The entities are stored in a static memory cache, and will not require database access if loaded again during the same page request.

The actual loading is done through a class that has to implement the DrupalEntityControllerInterface interface. By default, DrupalDefaultEntityController is used. Entity types can specify that a different class should be used by setting the 'controller class' key in hook_entity_info(). These classes can either implement the DrupalEntityControllerInterface interface, or, most commonly, extend the DrupalDefaultEntityController class. See node_entity_info() and the NodeController in node.module as an example.

@todo Remove $conditions in Drupal 8.

Parameters

$entity_type: The entity type to load, e.g. node or user.

$ids: An array of entity IDs, or FALSE to load all entities.

$conditions: (deprecated) An associative array of conditions on the base table, where the keys are the database fields and the values are the values those fields must have. Instead, it is preferable to use EntityFieldQuery to retrieve a list of entity IDs loadable by this function.

$reset: Whether to reset the internal cache for the requested entity type.

Return value

An array of entity objects indexed by their ids. When no results are found, an empty array is returned.

See also

hook_entity_info()

DrupalEntityControllerInterface

DrupalDefaultEntityController

EntityFieldQuery

7 calls to entity_load()
comment_load_multiple in modules/comment/comment.module
Load comments from the database.
file_file_download in modules/file/file.module
Implements hook_file_download().
file_load_multiple in includes/file.inc
Loads file objects from the database.
node_load_multiple in modules/node/node.module
Loads node entities from the database.
taxonomy_term_load_multiple in modules/taxonomy/taxonomy.module
Load multiple taxonomy terms based on certain conditions.

... See full list

1 string reference to 'entity_load'
DrupalDefaultEntityController::attachLoad in includes/entity.inc
Attaches data to entities upon loading.

File

includes/common.inc, line 7745
Common functions that many Drupal modules will need to reference.

Code

function entity_load($entity_type, $ids = FALSE, $conditions = array(), $reset = FALSE) {
  if ($reset) {
    entity_get_controller($entity_type)->resetCache();
  }
  return entity_get_controller($entity_type)->load($ids, $conditions);
}

Comments

Posted by bvanmeurs on

"Instead, it is preferable to use EntityFieldQuery to retrieve a list of entity IDs loadable by this function."

Example:

  $query = new EntityFieldQuery();

  $query
    ->entityCondition('entity_type', 'artwork', '=')
    ->propertyCondition('type', 'painting', '=');

  $result = $query->execute();
 
  $aids = array();
  foreach($result['artwork'] as $record) {
    $aids[] = $record->aid;
  }
  $artworks = entity_load('artwork', $aids);

Posted by axel.rutz on

for node loads eg look here:
http://stackoverflow.com/questions/6017317/entityfieldquery-multiple-alt...

Posted by rafinskipg on

Is it possible to use entity load with fields?? I tried but i can't make it work

Posted by Simix on

Yeah, put your fields in $conditions as array like this :
$items = entity_load('node', FALSE, array('type' => 'article', 'title' => 'mytitle'));

Posted by markie on

You would want to use an EntityFieldQuery instead. See http://drupal.org/node/1343708

Posted by alanom on

1) ...that calling entity_load() can cause that entity's cache to be updated (this happens in DrupalDefaultEntityController::load)

2) ...that if you want to reload of revert an entity to load it as it is on the database right now, not as it was when previously loaded or as it is in memory after being editted in memory, you don't need to use the final 'true' parameter which can have unintended consequences wiping caches of other entities of the same type, you can use entity_load_unchanged()

Posted by Spry_Julia on

This says that the return value contains "An array of entity objects indexed by their ids. When no results are found, an empty array is returned."

Can anyone tell me where the properties of the entity object are documented? I've searched the API documentation, as well as Google, and been unable to find this so far. Thanks!

Posted by kerasai on

There are no specific properties for entities, they will depend on what's defined in the hook_entity_info() of the module that implements the entity type. Other modules may add into the object through hooks, so what the entity object looks like will depend on what type of entity you're working with, fields defined for the entity, and the combination of modules that may hook in.

Posted by SelrahcD on

Can someone tell me why $id is not passed to resetCache like so :
entity_get_controller($entity_type)->resetCache($ids);
?
I don't see the point of loosing this information at this place.
Moreover, this create an issue with entitycache module(at least for users).

Posted by jweowu on

Unfortunately it's not that simple. The purpose of the $reset flag is to prevent the memory requirements for the request from ballooning when loading a great many nodes (e.g. consider a large search indexing cron run, which might load hundreds of nodes).

If in entity_load() you pass the ids to resetCache() then we firstly clear those specific entries from the cache, and then we load them from the database and store them in the cache, where they remain.

The next call to entity_load() in the sequence will not affect a newly-cached entity from the previous call (because $ids is different), and so the memory usage balloons.

What Drupal needs is an argument to entity_load() which says "give me the entity but DON'T cache it". That way, things which need to load lots of nodes and then discard them could take that approach without the side-effect of also discarding everything else.

Posted by jweowu on

It looks like the "load but don't cache" behaviour can be performed by specifying the revision id in the $conditions array. If a revision id is present, the loaded entity isn't cached (even if the specified revision is in fact the current revision).

Posted by jweowu on

I've raised API addition to resolve unwanted cache flushes when loading entities to discuss developing a solution to this.

Posted by dmatamales on

If you just want to look up a single entity ID, make sure you put it in as an array (at least in Drupal 7). I didn't read the parameters carefully enough, and that caused me a bit of grief. :P

<?php
      $entity = entity_load('field_collection_item', array('single_entity_id'));
?>