1 files changed, 119 insertions, 0 deletions
diff --git a/modules/system/system.api.php b/modules/system/system.api.php
index fe087415a..6ed576696 100644
--- a/modules/system/system.api.php
+++ b/modules/system/system.api.php
@@ -3309,6 +3309,13 @@ function hook_install() {
  * In order to call a function from your mymodule.module or an include file,
  * you need to explicitly load that file first.
  *
+ * During database updates the schema of any module could be out of date. For
+ * this reason, caution is needed when using any API function within an update
+ * function - particularly CRUD functions, functions that depend on the schema
+ * (for example by using drupal_write_record()), and any functions that invoke
+ * hooks. See @link update_api Update versions of API functions @endlink for
+ * details.
+ *
  * If your update task is potentially time-consuming, you'll need to implement a
  * multipass update to avoid PHP timeouts. Multipass updates use the $sandbox
  * parameter provided by the batch API (normally, $context['sandbox']) to store
@@ -3333,6 +3340,7 @@ function hook_install() {
  *
  * @see batch
  * @see schemaapi
+ * @see update_api
  * @see hook_update_last_removed()
  * @see update_get_update_list()
  */
@@ -4656,3 +4664,114 @@ function hook_filetransfer_info_alter(&$filetransfer_info) {
 /**
  * @} End of "addtogroup hooks".
  */
+
+/**
+ * @defgroup update_api Update versions of API functions
+ * @{
+ * Functions that are similar to normal API functions, but do not invoke hooks.
+ *
+ * These simplified versions of core API functions are provided for use by
+ * update functions (hook_update_N() implementations).
+ *
+ * During database updates the schema of any module could be out of date. For
+ * this reason, caution is needed when using any API function within an update
+ * function - particularly CRUD functions, functions that depend on the schema
+ * (for example by using drupal_write_record()), and any functions that invoke
+ * hooks.
+ *
+ * Instead, a simplified utility function should be used. If a utility version
+ * of the API function you require does not already exist, then you should
+ * create a new function. The new utility function should be named
+ * _update_N_mymodule_my_function(). N is the schema version the function acts
+ * on (the schema version is the number N from the hook_update_N()
+ * implementation where this schema was introduced, or a number following the
+ * same numbering scheme), and mymodule_my_function is the name of the original
+ * API function including the module's name.
+ *
+ * Examples:
+ * - _update_6000_mymodule_save(): This function performs a save operation
+ *   without invoking any hooks using the 6.x schema.
+ * - _update_7000_mymodule_save(): This function performs the same save
+ *   operation using the 7.x schema.
+ *
+ * The utility function should not invoke any hooks, and should perform database
+ * operations using functions from the
+ * @link database Database abstraction layer, @endlink
+ * like db_insert(), db_update(), db_delete(), db_query(), and so on.
+ *
+ * If a change to the schema necessitates a change to the utility function, a
+ * new function should be created with a name based on the version of the schema
+ * it acts on. See _update_7000_bar_get_types() and _update_7001_bar_get_types()
+ * in the code examples that follow.
+ *
+ * For example, foo.install could contain:
+ * @code
+ * function foo_update_dependencies() {
+ *   // foo_update_7010() needs to run after bar_update_7000().
+ *   $dependencies['foo'][7010] = array(
+ *     'bar' => 7000,
+ *   );
+ *
+ *   // foo_update_7036() needs to run after bar_update_7001().
+ *   $dependencies['foo'][7036] = array(
+ *     'bar' => 7001,
+ *   );
+ *
+ *   return $dependencies;
+ * }
+ *
+ * function foo_update_7000() {
+ *   // No updates have been run on the {bar_types} table yet, so this needs
+ *   // to work with the 6.x schema.
+ *   foreach (_update_6000_bar_get_types() as $type) {
+ *     // Rename a variable.
+ *   }
+ * }
+ *
+ * function foo_update_7010() {
+ *    // Since foo_update_7010() is going to run after bar_update_7000(), it
+ *    // needs to operate on the new schema, not the old one.
+ *    foreach (_update_7000_bar_get_types() as $type) {
+ *      // Rename a different variable.
+ *    }
+ * }
+ *
+ * function foo_update_7036() {
+ *   // This update will run after bar_update_7001().
+ *   foreach (_update_7001_bar_get_types() as $type) {
+ *   }
+ * }
+ * @endcode
+ *
+ * And bar.install could contain:
+ * @code
+ * function bar_update_7000() {
+ *   // Type and bundle are confusing, so we renamed the table.
+ *   db_rename_table('bar_types', 'bar_bundles');
+ * }
+ *
+ * function bar_update_7001() {
+ *   // Database table names should be singular when possible.
+ *   db_rename_table('bar_bundles', 'bar_bundle');
+ * }
+ *
+ * function _update_6000_bar_get_types() {
+ *   db_query('SELECT * FROM {bar_types}')->fetchAll();
+ * }
+ *
+ * function _update_7000_bar_get_types() {
+ *   db_query('SELECT * FROM {bar_bundles'})->fetchAll();
+ * }
+ *
+ * function _update_7001_bar_get_types() {
+ *   db_query('SELECT * FROM {bar_bundle}')->fetchAll();
+ * }
+ * @endcode
+ *
+ * @see hook_update_N()
+ * @see hook_update_dependencies()
+ */
+
+/**
+ * @} End of "defgroup update_api".
+ */