Commit 1df8d280 authored by jhodgdon's avatar jhodgdon

Issue #1134088 by Cottser, catch: Fix up documentation for update helper functions

parent 2944c1ce
......@@ -1125,17 +1125,3 @@ function update_variables_to_config($config_name, array $variable_map) {
// Delete the migrated variables.
db_delete('variable')->condition('name', array_keys($variable_map), 'IN')->execute();
}
/**
* @defgroup update-api-7.x-to-8.x Update versions of API functions
* @{
* Functions similar to normal API function but not firing hooks.
*
* During update, it is impossible to judge the consequences of firing a hook
* as it might hit a module not yet updated. So simplified versions of some
* core APIs are provided.
*/
/**
* @} End of "defgroup update-api-7.x-to-8.x".
*/
......@@ -169,7 +169,7 @@ function field_schema() {
/**
* Creates a field by writing directly to the database.
*
* @ingroup update-api-7.x-to-8.x
* @ingroup update_api
*/
function _update_7000_field_create_field(&$field) {
// Merge in default values.`
......@@ -247,7 +247,7 @@ function _update_7000_field_create_field(&$field) {
* @param $field_name
* The field name to delete.
*
* @ingroup update-api-7.x-to-8.x
* @ingroup update_api
*/
function _update_7000_field_delete_field($field_name) {
$table_name = 'field_data_' . $field_name;
......@@ -276,7 +276,7 @@ function _update_7000_field_delete_field($field_name) {
*
* BEWARE: This function deletes user data from the field storage tables.
*
* @ingroup update-api-7.x-to-8.x
* @ingroup update_api
*/
function _update_7000_field_delete_instance($field_name, $entity_type, $bundle) {
// Delete field instance configuration data.
......@@ -314,7 +314,7 @@ function _update_7000_field_delete_instance($field_name, $entity_type, $bundle)
* @return
* An array of fields matching $conditions, keyed by the property specified
* by the $key parameter.
* @ingroup update-api-7.x-to-8.x
* @ingroup update_api
*/
function _update_7000_field_read_fields(array $conditions = array(), $key = 'id') {
$fields = array();
......@@ -346,7 +346,7 @@ function _update_7000_field_read_fields(array $conditions = array(), $key = 'id'
/**
* Writes a field instance directly to the database.
*
* @ingroup update-api-7.x-to-8.x
* @ingroup update_api
*/
function _update_7000_field_create_instance($field, &$instance) {
// Merge in defaults.
......
......@@ -27,7 +27,7 @@ function field_sql_storage_schema() {
/**
* Writes field data directly to SQL storage.
*
* @ingroup update-api-7.x-to-8.x
* @ingroup update_api
*/
function _update_8000_field_sql_storage_write($entity_type, $bundle, $entity_id, $revision_id, $field_name, $data) {
$table_name = "field_data_{$field_name}";
......
......@@ -490,7 +490,7 @@ function node_uninstall() {
/**
* Fetches node types directly from the database.
*
* @ingroup update-api-7.x-to-8.x
* @ingroup update_api
*/
function _update_7000_node_get_types() {
$node_types = db_query('SELECT * FROM {node_type}')->fetchAllAssoc('type', PDO::FETCH_OBJ);
......
......@@ -2826,6 +2826,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
......@@ -2851,6 +2858,7 @@ function hook_install() {
*
* @see batch
* @see schemaapi
* @see update_api
* @see hook_update_last_removed()
* @see update_get_update_list()
*/
......@@ -3956,3 +3964,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_7000_mymodule_save(): This function performs a save operation
* without invoking any hooks using the 7.x schema.
* - _update_8000_mymodule_save(): This function performs the same save
* operation using the 8.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_8000_bar_get_types() and _update_8001_bar_get_types()
* in the code examples that follow.
*
* For example, foo.install could contain:
* @code
* function foo_update_dependencies() {
* // foo_update_8010() needs to run after bar_update_8000().
* $dependencies['foo'][8010] = array(
* 'bar' => 8000,
* );
*
* // foo_update_8036() needs to run after bar_update_8001().
* $dependencies['foo'][8036] = array(
* 'bar' => 8001,
* );
*
* return $dependencies;
* }
*
* function foo_update_8000() {
* // No updates have been run on the {bar_types} table yet, so this needs
* // to work with the 7.x schema.
* foreach (_update_7000_bar_get_types() as $type) {
* // Rename a variable.
* }
* }
*
* function foo_update_8010() {
* // Since foo_update_8010() is going to run after bar_update_8000(), it
* // needs to operate on the new schema, not the old one.
* foreach (_update_8000_bar_get_types() as $type) {
* // Rename a different variable.
* }
* }
*
* function foo_update_8036() {
* // This update will run after bar_update_8001().
* foreach (_update_8001_bar_get_types() as $type) {
* }
* }
* @endcode
*
* And bar.install could contain:
* @code
* function bar_update_8000() {
* // Type and bundle are confusing, so we renamed the table.
* db_rename_table('bar_types', 'bar_bundles');
* }
*
* function bar_update_8001() {
* // Database table names should be singular when possible.
* db_rename_table('bar_bundles', 'bar_bundle');
* }
*
* function _update_7000_bar_get_types() {
* db_query('SELECT * FROM {bar_types}')->fetchAll();
* }
*
* function _update_8000_bar_get_types() {
* db_query('SELECT * FROM {bar_bundles'})->fetchAll();
* }
*
* function _update_8001_bar_get_types() {
* db_query('SELECT * FROM {bar_bundle}')->fetchAll();
* }
* @endcode
*
* @see hook_update_N()
* @see hook_update_dependencies()
*/
/**
* @} End of "defgroup update_api".
*/
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment