From 92970454b9be889eb843d3da0be767018fefa98d Mon Sep 17 00:00:00 2001
From: Dave Reid <dave@davereid.net>
Date: Tue, 17 May 2011 21:29:54 -0500
Subject: [PATCH] Issue #1160566: Renamed entity_load() to entity_load_multiple() and added a real entity_load() for a single entity.

---
 includes/common.inc              |   48 ++++++++++++++++++++++++++++++++++++-
 includes/entity.inc              |    2 +-
 includes/file.inc                |    4 +-
 modules/comment/comment.module   |    5 +--
 modules/file/file.module         |    3 +-
 modules/node/node.api.php        |    4 +-
 modules/node/node.module         |   12 ++++-----
 modules/system/system.api.php    |    6 +++-
 modules/taxonomy/taxonomy.module |   17 +++++--------
 modules/user/user.module         |   13 ++++------
 10 files changed, 75 insertions(+), 39 deletions(-)

diff --git a/includes/common.inc b/includes/common.inc
index 95e03e8..c33d16e 100644
--- a/includes/common.inc
+++ b/includes/common.inc
@@ -7400,7 +7400,51 @@ function entity_create_stub_entity($entity_type, $ids) {
 }
 
 /**
- * Load entities from the database.
+ * Load an entity 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.
+ *
+ * @see hook_entity_info()
+ * @see entity_load_multiple()
+ * @see DrupalEntityControllerInterface
+ * @see DrupalDefaultEntityController
+ * @see EntityFieldQuery
+ *
+ * @param $entity_type
+ *   The entity type to load, e.g. node or user.
+ * @param $id
+ *   The entity IDs to load, or FALSE to be able to select the first all entities.
+ * @param $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 an entity ID loadable by this function.
+ * @param $reset
+ *   Whether to reset the internal cache for the requested entity type.
+ *
+ * @return
+ *   An entity object.
+ *
+ * @todo Remove $conditions in Drupal 8.
+ */
+function entity_load($entity_type, $id, $conditions = array(), $reset = FALSE) {
+  $ids = !empty($id) ? array($id) : FALSE;
+  $entities = entity_load_multiple($entity_type, $ids, $conditions, $reset);
+  return !empty($entities) ? reset($entities) : FALSE;
+}
+
+/**
+ * Load multiple 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.
@@ -7436,7 +7480,7 @@ function entity_create_stub_entity($entity_type, $ids) {
  *
  * @todo Remove $conditions in Drupal 8.
  */
-function entity_load($entity_type, $ids = FALSE, $conditions = array(), $reset = FALSE) {
+function entity_load_multiple($entity_type, $ids = FALSE, $conditions = array(), $reset = FALSE) {
   if ($reset) {
     entity_get_controller($entity_type)->resetCache();
   }
diff --git a/includes/entity.inc b/includes/entity.inc
index a3cdf74..40be52d 100644
--- a/includes/entity.inc
+++ b/includes/entity.inc
@@ -996,7 +996,7 @@ class EntityFieldQuery {
    *   the entities found:
    *   @code
    *     $result = $query->execute();
-   *     $entities = entity_load($my_type, array_keys($result[$my_type]));
+   *     $entities = entity_load_multiple($my_type, array_keys($result[$my_type]));
    *   @endcode
    */
   public function execute() {
diff --git a/includes/file.inc b/includes/file.inc
index b7a1204..e8c9e07 100644
--- a/includes/file.inc
+++ b/includes/file.inc
@@ -533,8 +533,8 @@ function file_create_htaccess($directory, $private = TRUE) {
  *
  * @todo Remove $conditions in Drupal 8.
  */
-function file_load_multiple($fids = array(), $conditions = array()) {
-  return entity_load('file', $fids, $conditions);
+function file_load_multiple($fids = array(), array $conditions = array()) {
+  return entity_load_multiple('file', $fids, $conditions);
 }
 
 /**
diff --git a/modules/comment/comment.module b/modules/comment/comment.module
index ec57dd4..23166f3 100644
--- a/modules/comment/comment.module
+++ b/modules/comment/comment.module
@@ -1660,7 +1660,7 @@ function comment_delete_multiple($cids) {
  * @todo Remove $conditions in Drupal 8.
  */
 function comment_load_multiple($cids = array(), $conditions = array()) {
-  return entity_load('comment', $cids, $conditions);
+  return entity_load_multiple('comment', $cids, $conditions);
 }
 
 /**
@@ -1672,8 +1672,7 @@ function comment_load_multiple($cids = array(), $conditions = array()) {
  *   The comment object.
  */
 function comment_load($cid) {
-  $comment = comment_load_multiple(array($cid));
-  return $comment ? $comment[$cid] : FALSE;
+  return entity_load('comment', $cid);
 }
 
 /**
diff --git a/modules/file/file.module b/modules/file/file.module
index 4002701..10cb4a1 100644
--- a/modules/file/file.module
+++ b/modules/file/file.module
@@ -160,8 +160,7 @@ function file_file_download($uri, $field_type = 'file') {
     foreach ($field_references as $entity_type => $type_references) {
       foreach ($type_references as $id => $reference) {
         // Try to load $entity and $field.
-        $entity = entity_load($entity_type, array($id));
-        $entity = reset($entity);
+        $entity = entity_load($entity_type, $id);
         $field = NULL;
         if ($entity) {
           // Load all fields for that entity.
diff --git a/modules/node/node.api.php b/modules/node/node.api.php
index 3e8029c..480036c 100644
--- a/modules/node/node.api.php
+++ b/modules/node/node.api.php
@@ -56,8 +56,8 @@
  *   - hook_entity_update() (all)
  *   - hook_node_access_records() (all)
  *   - hook_node_access_records_alter() (all)
- * - Loading a node (calling node_load(), node_load_multiple(), or
- *   entity_load() with $entity_type of 'node'):
+ * - Loading a node (calling node_load(), node_load_multiple(), entity_load()
+ *   or entity_load_multiple() with $entity_type of 'node'):
  *   - Node and revision information is read from database.
  *   - hook_load() (node-type-specific)
  *   - field_attach_load_revision() and field_attach_load()
diff --git a/modules/node/node.module b/modules/node/node.module
index d19cf29..afb64a6 100644
--- a/modules/node/node.module
+++ b/modules/node/node.module
@@ -886,7 +886,7 @@ function node_invoke($node, $hook, $a2 = NULL, $a3 = NULL, $a4 = NULL) {
  * from the database. Nodes are loaded into memory and will not require
  * database access if loaded again during the same page request.
  *
- * @see entity_load()
+ * @see entity_load_multiple()
  * @see EntityFieldQuery
  *
  * @param $nids
@@ -906,7 +906,7 @@ function node_invoke($node, $hook, $a2 = NULL, $a3 = NULL, $a4 = NULL) {
  * @todo Remove $conditions in Drupal 8.
  */
 function node_load_multiple($nids = array(), $conditions = array(), $reset = FALSE) {
-  return entity_load('node', $nids, $conditions, $reset);
+  return entity_load_multiple('node', $nids, $conditions, $reset);
 }
 
 /**
@@ -922,11 +922,9 @@ function node_load_multiple($nids = array(), $conditions = array(), $reset = FAL
  * @return
  *   A fully-populated node object.
  */
-function node_load($nid = NULL, $vid = NULL, $reset = FALSE) {
-  $nids = (isset($nid) ? array($nid) : array());
-  $conditions = (isset($vid) ? array('vid' => $vid) : array());
-  $node = node_load_multiple($nids, $conditions, $reset);
-  return $node ? reset($node) : FALSE;
+function node_load($nid, $vid = NULL, $reset = FALSE) {
+  $conditions = isset($vid) ? array('vid' => $vid) : array();
+  return entity_load('node', $nid, $conditions, $reset);
 }
 
 /**
diff --git a/modules/system/system.api.php b/modules/system/system.api.php
index 9f56aba..3c2ffc5 100644
--- a/modules/system/system.api.php
+++ b/modules/system/system.api.php
@@ -177,6 +177,7 @@ function hook_hook_info_alter(&$hooks) {
  *       display settings specific to the view mode.
  *
  * @see entity_load()
+ * @see entity_load_multiple()
  * @see hook_entity_info_alter()
  */
 function hook_entity_info() {
@@ -495,8 +496,9 @@ function hook_admin_paths_alter(&$paths) {
  * Act on entities as they are being prepared for view.
  *
  * Allows you to operate on multiple entities as they are being prepared for
- * view. Only use this if attaching the data during the entity_load() phase
- * is not appropriate, for example when attaching other 'entity' style objects.
+ * view. Only use this if attaching the data during the entity_load() or
+ * entity_load_multiple() phase is not appropriate, for example when attaching
+ * other 'entity' style objects.
  *
  * @param $entities
  *   The entities keyed by entity ID.
diff --git a/modules/taxonomy/taxonomy.module b/modules/taxonomy/taxonomy.module
index 50d2fd6..1b47fcc 100644
--- a/modules/taxonomy/taxonomy.module
+++ b/modules/taxonomy/taxonomy.module
@@ -1079,7 +1079,7 @@ class TaxonomyVocabularyController extends DrupalDefaultEntityController {
  * from the database. Terms are loaded into memory and will not require
  * database access if loaded again during the same page request.
  *
- * @see entity_load()
+ * @see entity_load_multiple()
  * @see EntityFieldQuery
  *
  * @param $tids
@@ -1097,7 +1097,7 @@ class TaxonomyVocabularyController extends DrupalDefaultEntityController {
  * @todo Remove $conditions in Drupal 8.
  */
 function taxonomy_term_load_multiple($tids = array(), $conditions = array()) {
-  return entity_load('taxonomy_term', $tids, $conditions);
+  return entity_load_multiple('taxonomy_term', $tids, $conditions);
 }
 
 /**
@@ -1107,7 +1107,7 @@ function taxonomy_term_load_multiple($tids = array(), $conditions = array()) {
  * vocabulary from the database. Terms are loaded into memory and will not
  * require database access if loaded again during the same page request.
  *
- * @see entity_load()
+ * @see entity_load_multiple()
  *
  * @param $vids
  *  An array of taxonomy vocabulary IDs, or FALSE to load all vocabularies.
@@ -1118,7 +1118,7 @@ function taxonomy_term_load_multiple($tids = array(), $conditions = array()) {
  *  An array of vocabulary objects, indexed by vid.
  */
 function taxonomy_vocabulary_load_multiple($vids = array(), $conditions = array()) {
-  return entity_load('taxonomy_vocabulary', $vids, $conditions);
+  return entity_load_multiple('taxonomy_vocabulary', $vids, $conditions);
 }
 
 /**
@@ -1132,8 +1132,7 @@ function taxonomy_vocabulary_load_multiple($vids = array(), $conditions = array(
  *   Results are statically cached.
  */
 function taxonomy_vocabulary_load($vid) {
-  $vocabularies = taxonomy_vocabulary_load_multiple(array($vid));
-  return reset($vocabularies);
+  return entity_load('taxonomy_vocabulary', $vid);
 }
 
 /**
@@ -1147,8 +1146,7 @@ function taxonomy_vocabulary_load($vid) {
  *   Results are statically cached.
  */
 function taxonomy_vocabulary_machine_name_load($name) {
-  $vocabularies = taxonomy_vocabulary_load_multiple(NULL, array('machine_name' => $name));
-  return reset($vocabularies);
+  return entity_load('taxonomy_vocabulary', FALSE, array('machine_name' => $name));
 }
 
 /**
@@ -1164,8 +1162,7 @@ function taxonomy_term_load($tid) {
   if (!is_numeric($tid)) {
     return FALSE;
   }
-  $term = taxonomy_term_load_multiple(array($tid), array());
-  return $term ? $term[$tid] : FALSE;
+  return entity_load('taxonomy_term', $tid);
 }
 
 /**
diff --git a/modules/user/user.module b/modules/user/user.module
index de72baf..7c5b869 100644
--- a/modules/user/user.module
+++ b/modules/user/user.module
@@ -259,7 +259,7 @@ function user_external_load($authname) {
  * @return
  *   An array of user objects, indexed by uid.
  *
- * @see entity_load()
+ * @see entity_load_multiple()
  * @see user_load()
  * @see user_load_by_mail()
  * @see user_load_by_name()
@@ -268,7 +268,7 @@ function user_external_load($authname) {
  * @todo Remove $conditions in Drupal 8.
  */
 function user_load_multiple($uids = array(), $conditions = array(), $reset = FALSE) {
-  return entity_load('user', $uids, $conditions, $reset);
+  return entity_load_multiple('user', $uids, $conditions, $reset);
 }
 
 /**
@@ -343,8 +343,7 @@ class UserController extends DrupalDefaultEntityController {
  * @see user_load_multiple()
  */
 function user_load($uid, $reset = FALSE) {
-  $users = user_load_multiple(array($uid), array(), $reset);
-  return reset($users);
+  return entity_load('user', $uid, array(), $reset);
 }
 
 /**
@@ -359,8 +358,7 @@ function user_load($uid, $reset = FALSE) {
  * @see user_load_multiple()
  */
 function user_load_by_mail($mail) {
-  $users = user_load_multiple(array(), array('mail' => $mail));
-  return reset($users);
+  return entity_load('user', FALSE, array('mail' => $mail));
 }
 
 /**
@@ -375,8 +373,7 @@ function user_load_by_mail($mail) {
  * @see user_load_multiple()
  */
 function user_load_by_name($name) {
-  $users = user_load_multiple(array(), array('name' => $name));
-  return reset($users);
+  return entity_load('user', FALSE, array('name' => $name));
 }
 
 /**
-- 
1.7.1