From 77f6e36f63bb59b3cac763b916116c74aab1ff9e Mon Sep 17 00:00:00 2001
From: Dries Buytaert <dries@buytaert.net>
Date: Sat, 26 Jun 2010 12:34:44 +0000
Subject: [PATCH] - Patch #836748 by aaronbauman, jhodgdon: improve
documentation about install/enable/etc. hook invocation order.
---
includes/module.inc | 24 +++++++++-
modules/system/system.api.php | 83 +++++++++++++++++++++--------------
2 files changed, 74 insertions(+), 33 deletions(-)
diff --git a/includes/module.inc b/includes/module.inc
index e6a8ff98acf8..dbd1978d03fc 100644
--- a/includes/module.inc
+++ b/includes/module.inc
@@ -286,8 +286,25 @@ function module_load_all_includes($type, $name = NULL) {
}
/**
- * Enable a given list of modules.
+ * Enables or installs a given list of modules.
*
+ * Definitions:
+ * - "Enabling" is the process of activating a module for use by Drupal.
+ * - "Disabling" is the process of deactivating a module.
+ * - "Installing" is the process of enabling it for the first time or after it
+ * has been uninstalled.
+ * - "Uninstalling" is the process of removing all traces of a module.
+ *
+ * Order of events:
+ * - Gather and add module dependencies to $module_list (if applicable).
+ * - For each module that is being enabled:
+ * - Install module schema and update system registries and caches.
+ * - If the module is being enabled for the first time or had been
+ * uninstalled, invoke hook_install() and add it to the list of installed
+ * modules.
+ * - Invoke hook_enable().
+ * - Invoke hook_modules_installed().
+ * - Invoke hook_modules_enabled().
* @param $module_list
* An array of module names.
* @param $enable_dependencies
@@ -297,6 +314,11 @@ function module_load_all_includes($type, $name = NULL) {
*
* @return
* FALSE if one or more dependencies are missing, TRUE otherwise.
+ *
+ * @see hook_install()
+ * @see hook_enable()
+ * @see hook_modules_installed()
+ * @see hook_modules_enabled()
*/
function module_enable($module_list, $enable_dependencies = TRUE) {
if ($enable_dependencies) {
diff --git a/modules/system/system.api.php b/modules/system/system.api.php
index 0a37d895182c..1191802b42f3 100644
--- a/modules/system/system.api.php
+++ b/modules/system/system.api.php
@@ -2050,15 +2050,18 @@ function hook_flush_caches() {
/**
* Perform necessary actions after modules are installed.
*
- * This function differs from hook_install() as it gives all other
- * modules a chance to perform actions when a module is installed,
- * whereas hook_install() will only be called on the module actually
- * being installed.
- *
- * @see hook_install()
+ * This function differs from hook_install() in that it gives all other modules
+ * a chance to perform actions when a module is installed, whereas
+ * hook_install() is only called on the module actually being installed. See
+ * module_enable() for a detailed description of the order in which install and
+ * enable hooks are invoked.
*
* @param $modules
* An array of the installed modules.
+ *
+ * @see module_enable()
+ * @see hook_modules_enabled()
+ * @see hook_install()
*/
function hook_modules_installed($modules) {
if (in_array('lousy_module', $modules)) {
@@ -2069,15 +2072,18 @@ function hook_modules_installed($modules) {
/**
* Perform necessary actions after modules are enabled.
*
- * This function differs from hook_enable() as it gives all other
- * modules a chance to perform actions when modules are enabled,
- * whereas hook_enable() will only be called on the module actually
- * being enabled.
- *
- * @see hook_enable()
+ * This function differs from hook_enable() in that it gives all other modules a
+ * chance to perform actions when modules are enabled, whereas hook_enable() is
+ * only called on the module actually being enabled. See module_enable() for a
+ * detailed description of the order in which install and enable hooks are
+ * invoked.
*
* @param $modules
* An array of the enabled modules.
+ *
+ * @see hook_enable()
+ * @see hook_modules_installed()
+ * @see module_enable()
*/
function hook_modules_enabled($modules) {
if (in_array('lousy_module', $modules)) {
@@ -2089,15 +2095,15 @@ function hook_modules_enabled($modules) {
/**
* Perform necessary actions after modules are disabled.
*
- * This function differs from hook_disable() as it gives all other
- * modules a chance to perform actions when modules are disabled,
- * whereas hook_disable() will only be called on the module actually
- * being disabled.
- *
- * @see hook_disable()
+ * This function differs from hook_disable() in that it gives all other modules
+ * a chance to perform actions when modules are disabled, whereas hook_disable()
+ * is only called on the module actually being disabled.
*
* @param $modules
* An array of the disabled modules.
+ *
+ * @see hook_disable()
+ * @see hook_modules_uninstalled()
*/
function hook_modules_disabled($modules) {
if (in_array('lousy_module', $modules)) {
@@ -2108,18 +2114,18 @@ function hook_modules_disabled($modules) {
/**
* Perform necessary actions after modules are uninstalled.
*
- * This function differs from hook_uninstall() as it gives all other
- * modules a chance to perform actions when a module is uninstalled,
- * whereas hook_uninstall() will only be called on the module actually
- * being uninstalled.
+ * This function differs from hook_uninstall() in that it gives all other
+ * modules a chance to perform actions when a module is uninstalled, whereas
+ * hook_uninstall() is only called on the module actually being uninstalled.
*
* It is recommended that you implement this module if your module
* stores data that may have been set by other modules.
*
- * @see hook_uninstall()
- *
* @param $modules
* An array of the uninstalled modules.
+ *
+ * @see hook_uninstall()
+ * @see hook_modules_disabled()
*/
function hook_modules_uninstalled($modules) {
foreach ($modules as $module) {
@@ -2683,11 +2689,11 @@ function hook_query_TAG_alter(QueryAlterableInterface $query) {
* If the module implements hook_schema(), the database tables will
* be created before this hook is fired.
*
- * The hook will be called the first time a module is installed, and the
- * module's schema version will be set to the module's greatest numbered update
- * hook. Because of this, anytime a hook_update_N() is added to the module, this
- * function needs to be updated to reflect the current version of the database
- * schema.
+ * This hook will only be called the first time a module is enabled or after it
+ * is re-enabled after being uninstalled. The module's schema version will be
+ * set to the module's greatest numbered update hook. Because of this, anytime a
+ * hook_update_N() is added to the module, this function needs to be updated to
+ * reflect the current version of the database schema.
*
* See the Schema API documentation at
* @link http://drupal.org/node/146843 http://drupal.org/node/146843 @endlink
@@ -2701,8 +2707,12 @@ function hook_query_TAG_alter(QueryAlterableInterface $query) {
* Please be sure that anything added or modified in this function that can
* be removed during uninstall should be removed with hook_uninstall().
*
- * @see hook_uninstall()
* @see hook_schema()
+ * @see module_enable()
+ * @see hook_enable()
+ * @see hook_disable()
+ * @see hook_uninstall()
+ * @see hook_modules_installed()
*/
function hook_install() {
// Populate the default {node_access} record.
@@ -2910,6 +2920,8 @@ function hook_update_last_removed() {
*
* @see hook_install()
* @see hook_schema()
+ * @see hook_disable()
+ * @see hook_modules_uninstalled()
*/
function hook_uninstall() {
variable_del('upload_file_types');
@@ -2918,7 +2930,11 @@ function hook_uninstall() {
/**
* Perform necessary actions after module is enabled.
*
- * The hook is called everytime module is enabled.
+ * The hook is called every time the module is enabled.
+ *
+ * @see module_enable()
+ * @see hook_install()
+ * @see hook_modules_enabled()
*/
function hook_enable() {
mymodule_cache_rebuild();
@@ -2927,7 +2943,10 @@ function hook_enable() {
/**
* Perform necessary actions before module is disabled.
*
- * The hook is called everytime module is disabled.
+ * The hook is called every time the module is disabled.
+ *
+ * @see hook_uninstall()
+ * @see hook_modules_disabled()
*/
function hook_disable() {
mymodule_cache_rebuild();
--
GitLab