Index: modules/system/system.api.php
===================================================================
RCS file: /cvs/drupal/drupal/modules/system/system.api.php,v
retrieving revision 1.114
diff -u -p -r1.114 system.api.php
--- modules/system/system.api.php 31 Dec 2009 13:22:35 -0000 1.114
+++ modules/system/system.api.php 1 Jan 2010 16:18:58 -0000
@@ -1758,191 +1758,6 @@ function hook_file_url_alter(&$uri) {
}
}
}
- /**
- * Check installation requirements and do status reporting.
- *
- * This hook has two closely related uses, determined by the $phase argument:
- * checking installation requirements ($phase == 'install')
- * and status reporting ($phase == 'runtime').
- *
- * Note that this hook, like all others dealing with installation and updates,
- * must reside in a module_name.install file, or it will not properly abort
- * the installation of the module if a critical requirement is missing.
- *
- * During the 'install' phase, modules can for example assert that
- * library or server versions are available or sufficient.
- * Note that the installation of a module can happen during installation of
- * Drupal itself (by install.php) with an installation profile or later by hand.
- * As a consequence, install-time requirements must be checked without access
- * to the full Drupal API, because it is not available during install.php.
- * For localization you should for example use $t = get_t() to
- * retrieve the appropriate localization function name (t() or st()).
- * If a requirement has a severity of REQUIREMENT_ERROR, install.php will abort
- * or at least the module will not install.
- * Other severity levels have no effect on the installation.
- * Module dependencies do not belong to these installation requirements,
- * but should be defined in the module's .info file.
- *
- * The 'runtime' phase is not limited to pure installation requirements
- * but can also be used for more general status information like maintenance
- * tasks and security issues.
- * The returned 'requirements' will be listed on the status report in the
- * administration section, with indication of the severity level.
- * Moreover, any requirement with a severity of REQUIREMENT_ERROR severity will
- * result in a notice on the the administration overview page.
- *
- * @param $phase
- * The phase in which hook_requirements is run:
- * - 'install': the module is being installed.
- * - 'runtime': the runtime requirements are being checked and shown on the
- * status report page.
- *
- * @return
- * A keyed array of requirements. Each requirement is itself an array with
- * the following items:
- * - 'title': the name of the requirement.
- * - 'value': the current value (e.g. version, time, level, ...). During
- * install phase, this should only be used for version numbers, do not set
- * it if not applicable.
- * - 'description': description of the requirement/status.
- * - 'severity': the requirement's result/severity level, one of:
- * - REQUIREMENT_INFO: For info only.
- * - REQUIREMENT_OK: The requirement is satisfied.
- * - REQUIREMENT_WARNING: The requirement failed with a warning.
- * - REQUIREMENT_ERROR: The requirement failed with an error.
- */
-function hook_requirements($phase) {
- $requirements = array();
- // Ensure translations don't break at install time
- $t = get_t();
-
- // Report Drupal version
- if ($phase == 'runtime') {
- $requirements['drupal'] = array(
- 'title' => $t('Drupal'),
- 'value' => VERSION,
- 'severity' => REQUIREMENT_INFO
- );
- }
-
- // Test PHP version
- $requirements['php'] = array(
- 'title' => $t('PHP'),
- 'value' => ($phase == 'runtime') ? l(phpversion(), 'admin/logs/status/php') : phpversion(),
- );
- if (version_compare(phpversion(), DRUPAL_MINIMUM_PHP) < 0) {
- $requirements['php']['description'] = $t('Your PHP installation is too old. Drupal requires at least PHP %version.', array('%version' => DRUPAL_MINIMUM_PHP));
- $requirements['php']['severity'] = REQUIREMENT_ERROR;
- }
-
- // Report cron status
- if ($phase == 'runtime') {
- $cron_last = variable_get('cron_last');
-
- if (is_numeric($cron_last)) {
- $requirements['cron']['value'] = $t('Last run !time ago', array('!time' => format_interval(REQUEST_TIME - $cron_last)));
- }
- else {
- $requirements['cron'] = array(
- 'description' => $t('Cron has not run. It appears cron jobs have not been setup on your system. Please check the help pages for configuring cron jobs.', array('@url' => 'http://drupal.org/cron')),
- 'severity' => REQUIREMENT_ERROR,
- 'value' => $t('Never run'),
- );
- }
-
- $requirements['cron']['description'] .= ' ' . t('You can run cron manually.', array('@cron' => url('admin/logs/status/run-cron')));
-
- $requirements['cron']['title'] = $t('Cron maintenance tasks');
- }
-
- return $requirements;
-}
-
-/**
- * Define the current version of the database schema.
- *
- * A Drupal schema definition is an array structure representing one or
- * more tables and their related keys and indexes. A schema is defined by
- * hook_schema() which must live in your module's .install file.
- *
- * By implementing hook_schema() and specifying the tables your module
- * declares, you can easily create and drop these tables on all
- * supported database engines. You don't have to deal with the
- * different SQL dialects for table creation and alteration of the
- * supported database engines.
- *
- * See the Schema API Handbook at http://drupal.org/node/146843 for
- * details on schema definition structures.
- *
- * @return
- * A schema definition structure array. For each element of the
- * array, the key is a table name and the value is a table structure
- * definition.
- */
-function hook_schema() {
- $schema['node'] = array(
- // example (partial) specification for table "node"
- 'description' => 'The base table for nodes.',
- 'fields' => array(
- 'nid' => array(
- 'description' => 'The primary identifier for a node.',
- 'type' => 'serial',
- 'unsigned' => TRUE,
- 'not null' => TRUE),
- 'vid' => array(
- 'description' => 'The current {node_revision}.vid version identifier.',
- 'type' => 'int',
- 'unsigned' => TRUE,
- 'not null' => TRUE,
- 'default' => 0),
- 'type' => array(
- 'description' => 'The {node_type} of this node.',
- 'type' => 'varchar',
- 'length' => 32,
- 'not null' => TRUE,
- 'default' => ''),
- 'title' => array(
- 'description' => 'The title of this node, always treated a non-markup plain text.',
- 'type' => 'varchar',
- 'length' => 255,
- 'not null' => TRUE,
- 'default' => ''),
- ),
- 'indexes' => array(
- 'node_changed' => array('changed'),
- 'node_created' => array('created'),
- ),
- 'unique keys' => array(
- 'nid_vid' => array('nid', 'vid'),
- 'vid' => array('vid')
- ),
- 'primary key' => array('nid'),
- );
- return $schema;
-}
-
-/**
- * Perform alterations to existing database schemas.
- *
- * When a module modifies the database structure of another module (by
- * changing, adding or removing fields, keys or indexes), it should
- * implement hook_schema_alter() to update the default $schema to take
- * it's changes into account.
- *
- * See hook_schema() for details on the schema definition structure.
- *
- * @param $schema
- * Nested array describing the schemas for all modules.
- */
-function hook_schema_alter(&$schema) {
- // Add field to existing schema.
- $schema['users']['fields']['timezone_id'] = array(
- 'type' => 'int',
- 'not null' => TRUE,
- 'default' => 0,
- 'description' => 'Per-user timezone configuration.',
- );
-}
/**
* Perform alterations to a structured query.
@@ -2008,252 +1823,42 @@ function hook_query_TAG_alter(QueryAlter
}
/**
- * Perform setup tasks when the module is installed.
- *
- * If the module implements hook_schema(), the database tables will
- * be created before this hook is fired.
+ * Perform necessary alterations to the list of files parsed by the registry.
*
- * 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.
+ * Modules can manually modify the list of files before the registry parses
+ * them. The $modules array provides the .info file information, which includes
+ * the list of files registered to each module. Any files in the list can then
+ * be added to the list of files that the registry will parse, or modify
+ * attributes of a file.
*
- * See the Schema API documentation at
- * @link http://drupal.org/node/146843 http://drupal.org/node/146843 @endlink
- * for details on hook_schema and how database tables are defined.
+ * A necessary alteration made by the core SimpleTest module is to force .test
+ * files provided by disabled modules into the list of files parsed by the
+ * registry.
*
- * Note that since this function is called from a full bootstrap, all functions
- * (including those in modules enabled by the current page request) are
- * available when this hook is called. Use cases could be displaying a user
- * message, or calling a module function necessary for initial setup, etc.
+ * @param $files
+ * List of files to be parsed by the registry. The list will contain
+ * files found in each enabled module's info file and the core includes
+ * directory. The array is keyed by the file path and contains an array of
+ * the related module's name and weight as used internally by
+ * _registry_update() and related functions.
*
- * Please be sure that anything added or modified in this function that can
- * be removed during uninstall should be removed with hook_uninstall().
+ * For example:
+ * @code
+ * $files["modules/system/system.module"] = array(
+ * 'module' => 'system',
+ * 'weight' => 0,
+ * );
+ * @endcode
+ * @param $modules
+ * An array containing all module information stored in the {system} table.
+ * Each element of the array also contains the module's .info file
+ * information in the property 'info'. An additional 'dir' property has been
+ * added to the module information which provides the path to the directory
+ * in which the module resides. The example shows how to take advantage of
+ * both properties.
*
- * @see hook_uninstall()
- * @see hook_schema()
- */
-function hook_install() {
- // Populate the default {node_access} record.
- db_insert('node_access')
- ->fields(array(
- 'nid' => 0,
- 'gid' => 0,
- 'realm' => 'all',
- 'grant_view' => 1,
- 'grant_update' => 0,
- 'grant_delete' => 0,
- ))
- ->execute();
-}
-
-/**
- * Perform a single update. For each patch which requires a database change add
- * a new hook_update_N() which will be called by update.php.
- *
- * The database updates are numbered sequentially according to the version of Drupal you are compatible with.
- *
- * Schema updates should adhere to the Schema API:
- * @link http://drupal.org/node/150215 http://drupal.org/node/150215 @endlink
- *
- * Database updates consist of 3 parts:
- * - 1 digit for Drupal core compatibility
- * - 1 digit for your module's major release version (e.g. is this the 5.x-1.* (1) or 5.x-2.* (2) series of your module?)
- * - 2 digits for sequential counting starting with 00
- *
- * The 2nd digit should be 0 for initial porting of your module to a new Drupal
- * core API.
- *
- * Examples:
- * - mymodule_update_5200()
- * - This is the first update to get the database ready to run mymodule 5.x-2.*.
- * - mymodule_update_6000()
- * - This is the required update for mymodule to run with Drupal core API 6.x.
- * - mymodule_update_6100()
- * - This is the first update to get the database ready to run mymodule 6.x-1.*.
- * - mymodule_update_6200()
- * - This is the first update to get the database ready to run mymodule 6.x-2.*.
- * Users can directly update from 5.x-2.* to 6.x-2.* and they get all 60XX
- * and 62XX updates, but not 61XX updates, because those reside in the
- * 6.x-1.x branch only.
- *
- * A good rule of thumb is to remove updates older than two major releases of
- * Drupal. See hook_update_last_removed() to notify Drupal about the removals.
- *
- * Never renumber update functions.
- *
- * Further information about releases and release numbers:
- * - @link http://drupal.org/handbook/version-info http://drupal.org/handbook/version-info @endlink
- * - @link http://drupal.org/node/93999 http://drupal.org/node/93999 @endlink (Overview of contributions branches and tags)
- * - @link http://drupal.org/handbook/cvs/releases http://drupal.org/handbook/cvs/releases @endlink
- *
- * Implementations of this hook should be placed in a mymodule.install file in
- * the same directory as mymodule.module. Drupal core's updates are implemented
- * using the system module as a name and stored in database/updates.inc.
- *
- * 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
- * information between successive calls, and the $sandbox['#finished'] value
- * to provide feedback regarding completion level.
- *
- * See the batch operations page for more information on how to use the batch API:
- * @link http://drupal.org/node/146843 http://drupal.org/node/146843 @endlink
- *
- * @throws DrupalUpdateException, PDOException
- * In case of error, update hooks should throw an instance of DrupalUpdateException
- * with a meaningful message for the user. If a database query fails for whatever
- * reason, it will throw a PDOException.
- *
- * @return
- * Optionally update hooks may return a translated string that will be displayed
- * to the user. If no message is returned, no message will be presented to the
- * user.
- */
-function hook_update_N(&$sandbox) {
- // For non-multipass updates, the signature can simply be;
- // function hook_update_N() {
-
- // For most updates, the following is sufficient.
- db_add_field('mytable1', 'newcol', array('type' => 'int', 'not null' => TRUE, 'description' => 'My new integer column.'));
-
- // However, for more complex operations that may take a long time,
- // you may hook into Batch API as in the following example.
-
- // Update 3 users at a time to have an exclamation point after their names.
- // (They're really happy that we can do batch API in this hook!)
- if (!isset($sandbox['progress'])) {
- $sandbox['progress'] = 0;
- $sandbox['current_uid'] = 0;
- // We'll -1 to disregard the uid 0...
- $sandbox['max'] = db_query('SELECT COUNT(DISTINCT uid) FROM {users}')->fetchField() - 1;
- }
- db_select('users', 'u')
- ->fields('u', array('uid', 'name'))
- ->condition('uid', $sandbox['current_uid'], '>')
- ->range(0, 3)
- ->orderBy('uid', 'ASC')
- ->execute();
- foreach ($users as $user) {
- $user->name .= '!';
- db_update('users')
- ->fields(array('name' => $user->name))
- ->condition('uid', $user->uid)
- ->execute();
-
- $sandbox['progress']++;
- $sandbox['current_uid'] = $user->uid;
- }
-
- $sandbox['#finished'] = empty($sandbox['max']) ? 1 : ($sandbox['progress'] / $sandbox['max']);
-
- // To display a message to the user when the update is completed, return it.
- // If you do not want to display a completion message, simply return nothing.
- return t('The update did what it was supposed to do.');
-
- // In case of an error, simply throw an exception with an error message.
- throw new DrupalUpdateException('Something went wrong; here is what you should do.');
-}
-
-/**
- * Return a number which is no longer available as hook_update_N().
- *
- * If you remove some update functions from your mymodule.install file, you
- * should notify Drupal of those missing functions. This way, Drupal can
- * ensure that no update is accidentally skipped.
- *
- * Implementations of this hook should be placed in a mymodule.install file in
- * the same directory as mymodule.module.
- *
- * @return
- * An integer, corresponding to hook_update_N() which has been removed from
- * mymodule.install.
- *
- * @see hook_update_N()
- */
-function hook_update_last_removed() {
- // We've removed the 5.x-1.x version of mymodule, including database updates.
- // The next update function is mymodule_update_5200().
- return 5103;
-}
-
-/**
- * Remove any information that the module sets.
- *
- * The information that the module should remove includes:
- * - variables that the module has set using variable_set() or system_settings_form()
- * - modifications to existing tables
- *
- * The module should not remove its entry from the {system} table. Database tables
- * defined by hook_schema() will be removed automatically.
- *
- * The uninstall hook will fire when the module gets uninstalled but before the
- * module's database tables are removed, allowing your module to query its own
- * tables during this routine.
- *
- * @see hook_install()
- * @see hook_schema()
- */
-function hook_uninstall() {
- variable_del('upload_file_types');
-}
-
-/**
- * Perform necessary actions after module is enabled.
- *
- * The hook is called everytime module is enabled.
- */
-function hook_enable() {
- mymodule_cache_rebuild();
-}
-
-/**
- * Perform necessary actions before module is disabled.
- *
- * The hook is called everytime module is disabled.
- */
-function hook_disable() {
- mymodule_cache_rebuild();
-}
-
-/**
- * Perform necessary alterations to the list of files parsed by the registry.
- *
- * Modules can manually modify the list of files before the registry parses
- * them. The $modules array provides the .info file information, which includes
- * the list of files registered to each module. Any files in the list can then
- * be added to the list of files that the registry will parse, or modify
- * attributes of a file.
- *
- * A necessary alteration made by the core SimpleTest module is to force .test
- * files provided by disabled modules into the list of files parsed by the
- * registry.
- *
- * @param $files
- * List of files to be parsed by the registry. The list will contain
- * files found in each enabled module's info file and the core includes
- * directory. The array is keyed by the file path and contains an array of
- * the related module's name and weight as used internally by
- * _registry_update() and related functions.
- *
- * For example:
- * @code
- * $files["modules/system/system.module"] = array(
- * 'module' => 'system',
- * 'weight' => 0,
- * );
- * @endcode
- * @param $modules
- * An array containing all module information stored in the {system} table.
- * Each element of the array also contains the module's .info file
- * information in the property 'info'. An additional 'dir' property has been
- * added to the module information which provides the path to the directory
- * in which the module resides. The example shows how to take advantage of
- * both properties.
- *
- * @see _registry_update()
- * @see simpletest_test_get_all()
+ * @see _registry_update()
+ * @see simpletest_test_get_all()
*/
function hook_registry_files_alter(&$files, $modules) {
foreach ($modules as $module) {
@@ -2906,5 +2511,412 @@ function hook_username_alter(&$name, $ac
}
/**
+ * @defgroup hooks_file_module_dot_install Install file hooks
+ * @{
+ * Hooks whose implementation should be placed in the module's .install file.
+ *
+ * See also @link hooks the full list of hooks @endlink
+ */
+ /**
+ * Check installation requirements and do status reporting.
+ *
+ * This hook has two closely related uses, determined by the $phase argument:
+ * checking installation requirements ($phase == 'install')
+ * and status reporting ($phase == 'runtime').
+ *
+ * Note that this hook, like all others dealing with installation and updates,
+ * must reside in a module_name.install file, or it will not properly abort
+ * the installation of the module if a critical requirement is missing.
+ *
+ * During the 'install' phase, modules can for example assert that
+ * library or server versions are available or sufficient.
+ * Note that the installation of a module can happen during installation of
+ * Drupal itself (by install.php) with an installation profile or later by hand.
+ * As a consequence, install-time requirements must be checked without access
+ * to the full Drupal API, because it is not available during install.php.
+ * For localization you should for example use $t = get_t() to
+ * retrieve the appropriate localization function name (t() or st()).
+ * If a requirement has a severity of REQUIREMENT_ERROR, install.php will abort
+ * or at least the module will not install.
+ * Other severity levels have no effect on the installation.
+ * Module dependencies do not belong to these installation requirements,
+ * but should be defined in the module's .info file.
+ *
+ * The 'runtime' phase is not limited to pure installation requirements
+ * but can also be used for more general status information like maintenance
+ * tasks and security issues.
+ * The returned 'requirements' will be listed on the status report in the
+ * administration section, with indication of the severity level.
+ * Moreover, any requirement with a severity of REQUIREMENT_ERROR severity will
+ * result in a notice on the the administration overview page.
+ *
+ * @param $phase
+ * The phase in which hook_requirements is run:
+ * - 'install': the module is being installed.
+ * - 'runtime': the runtime requirements are being checked and shown on the
+ * status report page.
+ *
+ * @return
+ * A keyed array of requirements. Each requirement is itself an array with
+ * the following items:
+ * - 'title': the name of the requirement.
+ * - 'value': the current value (e.g. version, time, level, ...). During
+ * install phase, this should only be used for version numbers, do not set
+ * it if not applicable.
+ * - 'description': description of the requirement/status.
+ * - 'severity': the requirement's result/severity level, one of:
+ * - REQUIREMENT_INFO: For info only.
+ * - REQUIREMENT_OK: The requirement is satisfied.
+ * - REQUIREMENT_WARNING: The requirement failed with a warning.
+ * - REQUIREMENT_ERROR: The requirement failed with an error.
+ */
+function hook_requirements($phase) {
+ $requirements = array();
+ // Ensure translations don't break at install time
+ $t = get_t();
+
+ // Report Drupal version
+ if ($phase == 'runtime') {
+ $requirements['drupal'] = array(
+ 'title' => $t('Drupal'),
+ 'value' => VERSION,
+ 'severity' => REQUIREMENT_INFO
+ );
+ }
+
+ // Test PHP version
+ $requirements['php'] = array(
+ 'title' => $t('PHP'),
+ 'value' => ($phase == 'runtime') ? l(phpversion(), 'admin/logs/status/php') : phpversion(),
+ );
+ if (version_compare(phpversion(), DRUPAL_MINIMUM_PHP) < 0) {
+ $requirements['php']['description'] = $t('Your PHP installation is too old. Drupal requires at least PHP %version.', array('%version' => DRUPAL_MINIMUM_PHP));
+ $requirements['php']['severity'] = REQUIREMENT_ERROR;
+ }
+
+ // Report cron status
+ if ($phase == 'runtime') {
+ $cron_last = variable_get('cron_last');
+
+ if (is_numeric($cron_last)) {
+ $requirements['cron']['value'] = $t('Last run !time ago', array('!time' => format_interval(REQUEST_TIME - $cron_last)));
+ }
+ else {
+ $requirements['cron'] = array(
+ 'description' => $t('Cron has not run. It appears cron jobs have not been setup on your system. Please check the help pages for configuring cron jobs.', array('@url' => 'http://drupal.org/cron')),
+ 'severity' => REQUIREMENT_ERROR,
+ 'value' => $t('Never run'),
+ );
+ }
+
+ $requirements['cron']['description'] .= ' ' . t('You can run cron manually.', array('@cron' => url('admin/logs/status/run-cron')));
+
+ $requirements['cron']['title'] = $t('Cron maintenance tasks');
+ }
+
+ return $requirements;
+}
+
+/**
+ * Define the current version of the database schema.
+ *
+ * A Drupal schema definition is an array structure representing one or
+ * more tables and their related keys and indexes. A schema is defined by
+ * hook_schema() which must live in your module's .install file.
+ *
+ * By implementing hook_schema() and specifying the tables your module
+ * declares, you can easily create and drop these tables on all
+ * supported database engines. You don't have to deal with the
+ * different SQL dialects for table creation and alteration of the
+ * supported database engines.
+ *
+ * See the Schema API Handbook at http://drupal.org/node/146843 for
+ * details on schema definition structures.
+ *
+ * @return
+ * A schema definition structure array. For each element of the
+ * array, the key is a table name and the value is a table structure
+ * definition.
+ */
+function hook_schema() {
+ $schema['node'] = array(
+ // example (partial) specification for table "node"
+ 'description' => 'The base table for nodes.',
+ 'fields' => array(
+ 'nid' => array(
+ 'description' => 'The primary identifier for a node.',
+ 'type' => 'serial',
+ 'unsigned' => TRUE,
+ 'not null' => TRUE),
+ 'vid' => array(
+ 'description' => 'The current {node_revision}.vid version identifier.',
+ 'type' => 'int',
+ 'unsigned' => TRUE,
+ 'not null' => TRUE,
+ 'default' => 0),
+ 'type' => array(
+ 'description' => 'The {node_type} of this node.',
+ 'type' => 'varchar',
+ 'length' => 32,
+ 'not null' => TRUE,
+ 'default' => ''),
+ 'title' => array(
+ 'description' => 'The title of this node, always treated a non-markup plain text.',
+ 'type' => 'varchar',
+ 'length' => 255,
+ 'not null' => TRUE,
+ 'default' => ''),
+ ),
+ 'indexes' => array(
+ 'node_changed' => array('changed'),
+ 'node_created' => array('created'),
+ ),
+ 'unique keys' => array(
+ 'nid_vid' => array('nid', 'vid'),
+ 'vid' => array('vid')
+ ),
+ 'primary key' => array('nid'),
+ );
+ return $schema;
+}
+
+/**
+ * Perform alterations to existing database schemas.
+ *
+ * When a module modifies the database structure of another module (by
+ * changing, adding or removing fields, keys or indexes), it should
+ * implement hook_schema_alter() to update the default $schema to take
+ * it's changes into account.
+ *
+ * See hook_schema() for details on the schema definition structure.
+ *
+ * @param $schema
+ * Nested array describing the schemas for all modules.
+ */
+function hook_schema_alter(&$schema) {
+ // Add field to existing schema.
+ $schema['users']['fields']['timezone_id'] = array(
+ 'type' => 'int',
+ 'not null' => TRUE,
+ 'default' => 0,
+ 'description' => 'Per-user timezone configuration.',
+ );
+}
+
+/**
+ * Perform setup tasks when the module is installed.
+ *
+ * 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.
+ *
+ * See the Schema API documentation at
+ * @link http://drupal.org/node/146843 http://drupal.org/node/146843 @endlink
+ * for details on hook_schema and how database tables are defined.
+ *
+ * Note that since this function is called from a full bootstrap, all functions
+ * (including those in modules enabled by the current page request) are
+ * available when this hook is called. Use cases could be displaying a user
+ * message, or calling a module function necessary for initial setup, etc.
+ *
+ * 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()
+ */
+function hook_install() {
+ // Populate the default {node_access} record.
+ db_insert('node_access')
+ ->fields(array(
+ 'nid' => 0,
+ 'gid' => 0,
+ 'realm' => 'all',
+ 'grant_view' => 1,
+ 'grant_update' => 0,
+ 'grant_delete' => 0,
+ ))
+ ->execute();
+}
+
+/**
+ * Perform a single update. For each patch which requires a database change add
+ * a new hook_update_N() which will be called by update.php.
+ *
+ * The database updates are numbered sequentially according to the version of Drupal you are compatible with.
+ *
+ * Schema updates should adhere to the Schema API:
+ * @link http://drupal.org/node/150215 http://drupal.org/node/150215 @endlink
+ *
+ * Database updates consist of 3 parts:
+ * - 1 digit for Drupal core compatibility
+ * - 1 digit for your module's major release version (e.g. is this the 5.x-1.* (1) or 5.x-2.* (2) series of your module?)
+ * - 2 digits for sequential counting starting with 00
+ *
+ * The 2nd digit should be 0 for initial porting of your module to a new Drupal
+ * core API.
+ *
+ * Examples:
+ * - mymodule_update_5200()
+ * - This is the first update to get the database ready to run mymodule 5.x-2.*.
+ * - mymodule_update_6000()
+ * - This is the required update for mymodule to run with Drupal core API 6.x.
+ * - mymodule_update_6100()
+ * - This is the first update to get the database ready to run mymodule 6.x-1.*.
+ * - mymodule_update_6200()
+ * - This is the first update to get the database ready to run mymodule 6.x-2.*.
+ * Users can directly update from 5.x-2.* to 6.x-2.* and they get all 60XX
+ * and 62XX updates, but not 61XX updates, because those reside in the
+ * 6.x-1.x branch only.
+ *
+ * A good rule of thumb is to remove updates older than two major releases of
+ * Drupal. See hook_update_last_removed() to notify Drupal about the removals.
+ *
+ * Never renumber update functions.
+ *
+ * Further information about releases and release numbers:
+ * - @link http://drupal.org/handbook/version-info http://drupal.org/handbook/version-info @endlink
+ * - @link http://drupal.org/node/93999 http://drupal.org/node/93999 @endlink (Overview of contributions branches and tags)
+ * - @link http://drupal.org/handbook/cvs/releases http://drupal.org/handbook/cvs/releases @endlink
+ *
+ * Implementations of this hook should be placed in a mymodule.install file in
+ * the same directory as mymodule.module. Drupal core's updates are implemented
+ * using the system module as a name and stored in database/updates.inc.
+ *
+ * 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
+ * information between successive calls, and the $sandbox['#finished'] value
+ * to provide feedback regarding completion level.
+ *
+ * See the batch operations page for more information on how to use the batch API:
+ * @link http://drupal.org/node/146843 http://drupal.org/node/146843 @endlink
+ *
+ * @throws DrupalUpdateException, PDOException
+ * In case of error, update hooks should throw an instance of DrupalUpdateException
+ * with a meaningful message for the user. If a database query fails for whatever
+ * reason, it will throw a PDOException.
+ *
+ * @return
+ * Optionally update hooks may return a translated string that will be displayed
+ * to the user. If no message is returned, no message will be presented to the
+ * user.
+ */
+function hook_update_N(&$sandbox) {
+ // For non-multipass updates, the signature can simply be;
+ // function hook_update_N() {
+
+ // For most updates, the following is sufficient.
+ db_add_field('mytable1', 'newcol', array('type' => 'int', 'not null' => TRUE, 'description' => 'My new integer column.'));
+
+ // However, for more complex operations that may take a long time,
+ // you may hook into Batch API as in the following example.
+
+ // Update 3 users at a time to have an exclamation point after their names.
+ // (They're really happy that we can do batch API in this hook!)
+ if (!isset($sandbox['progress'])) {
+ $sandbox['progress'] = 0;
+ $sandbox['current_uid'] = 0;
+ // We'll -1 to disregard the uid 0...
+ $sandbox['max'] = db_query('SELECT COUNT(DISTINCT uid) FROM {users}')->fetchField() - 1;
+ }
+ db_select('users', 'u')
+ ->fields('u', array('uid', 'name'))
+ ->condition('uid', $sandbox['current_uid'], '>')
+ ->range(0, 3)
+ ->orderBy('uid', 'ASC')
+ ->execute();
+ foreach ($users as $user) {
+ $user->name .= '!';
+ db_update('users')
+ ->fields(array('name' => $user->name))
+ ->condition('uid', $user->uid)
+ ->execute();
+
+ $sandbox['progress']++;
+ $sandbox['current_uid'] = $user->uid;
+ }
+
+ $sandbox['#finished'] = empty($sandbox['max']) ? 1 : ($sandbox['progress'] / $sandbox['max']);
+
+ // To display a message to the user when the update is completed, return it.
+ // If you do not want to display a completion message, simply return nothing.
+ return t('The update did what it was supposed to do.');
+
+ // In case of an error, simply throw an exception with an error message.
+ throw new DrupalUpdateException('Something went wrong; here is what you should do.');
+}
+
+/**
+ * Return a number which is no longer available as hook_update_N().
+ *
+ * If you remove some update functions from your mymodule.install file, you
+ * should notify Drupal of those missing functions. This way, Drupal can
+ * ensure that no update is accidentally skipped.
+ *
+ * Implementations of this hook should be placed in a mymodule.install file in
+ * the same directory as mymodule.module.
+ *
+ * @return
+ * An integer, corresponding to hook_update_N() which has been removed from
+ * mymodule.install.
+ *
+ * @see hook_update_N()
+ */
+function hook_update_last_removed() {
+ // We've removed the 5.x-1.x version of mymodule, including database updates.
+ // The next update function is mymodule_update_5200().
+ return 5103;
+}
+
+/**
+ * Remove any information that the module sets.
+ *
+ * The information that the module should remove includes:
+ * - variables that the module has set using variable_set() or system_settings_form()
+ * - modifications to existing tables
+ *
+ * The module should not remove its entry from the {system} table. Database tables
+ * defined by hook_schema() will be removed automatically.
+ *
+ * The uninstall hook will fire when the module gets uninstalled but before the
+ * module's database tables are removed, allowing your module to query its own
+ * tables during this routine.
+ *
+ * @see hook_install()
+ * @see hook_schema()
+ */
+function hook_uninstall() {
+ variable_del('upload_file_types');
+}
+
+/**
+ * Perform necessary actions after module is enabled.
+ *
+ * The hook is called everytime module is enabled.
+ */
+function hook_enable() {
+ mymodule_cache_rebuild();
+}
+
+/**
+ * Perform necessary actions before module is disabled.
+ *
+ * The hook is called everytime module is disabled.
+ */
+function hook_disable() {
+ mymodule_cache_rebuild();
+}
+
+/**
+ * @} End of "defgroup hooks_file_module_dot_install".
+ */
+
+/**
* @} End of "addtogroup hooks".
*/