Commit 77f6e36f authored by Dries's avatar Dries

- Patch #836748 by aaronbauman, jhodgdon: improve documentation about...

- Patch #836748 by aaronbauman, jhodgdon: improve documentation about install/enable/etc. hook invocation order.
parent a7bbd6d1
...@@ -286,8 +286,25 @@ function module_load_all_includes($type, $name = NULL) { ...@@ -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 * @param $module_list
* An array of module names. * An array of module names.
* @param $enable_dependencies * @param $enable_dependencies
...@@ -297,6 +314,11 @@ function module_load_all_includes($type, $name = NULL) { ...@@ -297,6 +314,11 @@ function module_load_all_includes($type, $name = NULL) {
* *
* @return * @return
* FALSE if one or more dependencies are missing, TRUE otherwise. * 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) { function module_enable($module_list, $enable_dependencies = TRUE) {
if ($enable_dependencies) { if ($enable_dependencies) {
......
...@@ -2050,15 +2050,18 @@ function hook_flush_caches() { ...@@ -2050,15 +2050,18 @@ function hook_flush_caches() {
/** /**
* Perform necessary actions after modules are installed. * Perform necessary actions after modules are installed.
* *
* This function differs from hook_install() as it gives all other * This function differs from hook_install() in that it gives all other modules
* modules a chance to perform actions when a module is installed, * a chance to perform actions when a module is installed, whereas
* whereas hook_install() will only be called on the module actually * hook_install() is only called on the module actually being installed. See
* being installed. * module_enable() for a detailed description of the order in which install and
* * enable hooks are invoked.
* @see hook_install()
* *
* @param $modules * @param $modules
* An array of the installed modules. * An array of the installed modules.
*
* @see module_enable()
* @see hook_modules_enabled()
* @see hook_install()
*/ */
function hook_modules_installed($modules) { function hook_modules_installed($modules) {
if (in_array('lousy_module', $modules)) { if (in_array('lousy_module', $modules)) {
...@@ -2069,15 +2072,18 @@ function hook_modules_installed($modules) { ...@@ -2069,15 +2072,18 @@ function hook_modules_installed($modules) {
/** /**
* Perform necessary actions after modules are enabled. * Perform necessary actions after modules are enabled.
* *
* This function differs from hook_enable() as it gives all other * This function differs from hook_enable() in that it gives all other modules a
* modules a chance to perform actions when modules are enabled, * chance to perform actions when modules are enabled, whereas hook_enable() is
* whereas hook_enable() will only be called on the module actually * only called on the module actually being enabled. See module_enable() for a
* being enabled. * detailed description of the order in which install and enable hooks are
* * invoked.
* @see hook_enable()
* *
* @param $modules * @param $modules
* An array of the enabled modules. * An array of the enabled modules.
*
* @see hook_enable()
* @see hook_modules_installed()
* @see module_enable()
*/ */
function hook_modules_enabled($modules) { function hook_modules_enabled($modules) {
if (in_array('lousy_module', $modules)) { if (in_array('lousy_module', $modules)) {
...@@ -2089,15 +2095,15 @@ function hook_modules_enabled($modules) { ...@@ -2089,15 +2095,15 @@ function hook_modules_enabled($modules) {
/** /**
* Perform necessary actions after modules are disabled. * Perform necessary actions after modules are disabled.
* *
* This function differs from hook_disable() as it gives all other * This function differs from hook_disable() in that it gives all other modules
* modules a chance to perform actions when modules are disabled, * a chance to perform actions when modules are disabled, whereas hook_disable()
* whereas hook_disable() will only be called on the module actually * is only called on the module actually being disabled.
* being disabled.
*
* @see hook_disable()
* *
* @param $modules * @param $modules
* An array of the disabled modules. * An array of the disabled modules.
*
* @see hook_disable()
* @see hook_modules_uninstalled()
*/ */
function hook_modules_disabled($modules) { function hook_modules_disabled($modules) {
if (in_array('lousy_module', $modules)) { if (in_array('lousy_module', $modules)) {
...@@ -2108,18 +2114,18 @@ function hook_modules_disabled($modules) { ...@@ -2108,18 +2114,18 @@ function hook_modules_disabled($modules) {
/** /**
* Perform necessary actions after modules are uninstalled. * Perform necessary actions after modules are uninstalled.
* *
* This function differs from hook_uninstall() as it gives all other * This function differs from hook_uninstall() in that it gives all other
* modules a chance to perform actions when a module is uninstalled, * modules a chance to perform actions when a module is uninstalled, whereas
* whereas hook_uninstall() will only be called on the module actually * hook_uninstall() is only called on the module actually being uninstalled.
* being uninstalled.
* *
* It is recommended that you implement this module if your module * It is recommended that you implement this module if your module
* stores data that may have been set by other modules. * stores data that may have been set by other modules.
* *
* @see hook_uninstall()
*
* @param $modules * @param $modules
* An array of the uninstalled modules. * An array of the uninstalled modules.
*
* @see hook_uninstall()
* @see hook_modules_disabled()
*/ */
function hook_modules_uninstalled($modules) { function hook_modules_uninstalled($modules) {
foreach ($modules as $module) { foreach ($modules as $module) {
...@@ -2683,11 +2689,11 @@ function hook_query_TAG_alter(QueryAlterableInterface $query) { ...@@ -2683,11 +2689,11 @@ function hook_query_TAG_alter(QueryAlterableInterface $query) {
* If the module implements hook_schema(), the database tables will * If the module implements hook_schema(), the database tables will
* be created before this hook is fired. * be created before this hook is fired.
* *
* The hook will be called the first time a module is installed, and the * This hook will only be called the first time a module is enabled or after it
* module's schema version will be set to the module's greatest numbered update * is re-enabled after being uninstalled. The module's schema version will be
* hook. Because of this, anytime a hook_update_N() is added to the module, this * set to the module's greatest numbered update hook. Because of this, anytime a
* function needs to be updated to reflect the current version of the database * hook_update_N() is added to the module, this function needs to be updated to
* schema. * reflect the current version of the database schema.
* *
* See the Schema API documentation at * See the Schema API documentation at
* @link http://drupal.org/node/146843 http://drupal.org/node/146843 @endlink * @link http://drupal.org/node/146843 http://drupal.org/node/146843 @endlink
...@@ -2701,8 +2707,12 @@ function hook_query_TAG_alter(QueryAlterableInterface $query) { ...@@ -2701,8 +2707,12 @@ function hook_query_TAG_alter(QueryAlterableInterface $query) {
* Please be sure that anything added or modified in this function that can * Please be sure that anything added or modified in this function that can
* be removed during uninstall should be removed with hook_uninstall(). * be removed during uninstall should be removed with hook_uninstall().
* *
* @see hook_uninstall()
* @see hook_schema() * @see hook_schema()
* @see module_enable()
* @see hook_enable()
* @see hook_disable()
* @see hook_uninstall()
* @see hook_modules_installed()
*/ */
function hook_install() { function hook_install() {
// Populate the default {node_access} record. // Populate the default {node_access} record.
...@@ -2910,6 +2920,8 @@ function hook_update_last_removed() { ...@@ -2910,6 +2920,8 @@ function hook_update_last_removed() {
* *
* @see hook_install() * @see hook_install()
* @see hook_schema() * @see hook_schema()
* @see hook_disable()
* @see hook_modules_uninstalled()
*/ */
function hook_uninstall() { function hook_uninstall() {
variable_del('upload_file_types'); variable_del('upload_file_types');
...@@ -2918,7 +2930,11 @@ function hook_uninstall() { ...@@ -2918,7 +2930,11 @@ function hook_uninstall() {
/** /**
* Perform necessary actions after module is enabled. * 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() { function hook_enable() {
mymodule_cache_rebuild(); mymodule_cache_rebuild();
...@@ -2927,7 +2943,10 @@ function hook_enable() { ...@@ -2927,7 +2943,10 @@ function hook_enable() {
/** /**
* Perform necessary actions before module is disabled. * 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() { function hook_disable() {
mymodule_cache_rebuild(); mymodule_cache_rebuild();
......
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