install.php
<?php
// $Id: install.php,v 1.7.2.4 2009/01/17 20:47:33 davereid Exp $
/**
* @file
* Documentation for the installation and update system.
*
* The update system is used by modules to provide database updates which are
* run with update.php.
*
* Implementations of these hooks should be placed in a mymodule.install file in
* the same directory as mymodule.module.
*/
/**
* @addtogroup hooks
* @{
*/
/**
* Check installation requirements that need to be satisfied.
*
* A module is expected to return a list of requirements and whether they are
* satisfied. This information is used both during installation and on the
* status report in the administration section.
*
* 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.
*
* Appropriate checks are for library or server versions, maintenance tasks,
* security, ... Module dependencies on the other hand do not belong here.
* Install-time requirements must be checked without access to the full
* Drupal API.
*
* Requirements can have one of four severity levels:
* - 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.
*
* Note that you need to use $t = get_t(); to retrieve the appropriate
* localisation function name (t or st).
*
* @param $phase
* The phase in which hook_requirements is run:
* - 'install': the module is being installed (either during install.php, or
* later by hand). Any requirement with REQUIREMENT_ERROR
* severity will cause install to abort.
* - 'runtime': the runtime requirements are being checked and shown on the
* status report page. Any requirement with REQUIREMENT_ERROR
* severity will cause a notice to appear at /admin.
*
* @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, ...).
* - 'description': optional notice for the status report.
* - 'severity': the requirement's result/severity (defaults to OK).
*/
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', NULL);
if (is_numeric($cron_last)) {
$requirements['cron']['value'] = $t('Last run !time ago', array('!time' => format_interval(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 <a href="@url">configuring cron jobs</a>.', array('@url' => 'http://drupal.org/cron')),
'severity' => REQUIREMENT_ERROR,
'value' => $t('Never run'),
);
}
$requirements['cron']['description'] .= ' '. t('You can <a href="@cron">run cron manually</a>.', array('@cron' => url('admin/logs/status/run-cron')));
$requirements['cron']['title'] = $t('Cron maintenance tasks');
}
return $requirements;
}
/**
* Install the current version of the database schema.
*
* 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.
*
* Table names in the CREATE queries should be wrapped with curly braces so that
* they're prefixed correctly, see db_prefix_tables() for more on this.
*
* 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.
*/
function hook_install() {
switch ($GLOBALS['db_type']) {
case 'mysql':
case 'mysqli':
db_query("CREATE TABLE {event} (
nid int(10) unsigned NOT NULL default '0',
event_start int(10) unsigned NOT NULL default '0',
event_end int(10) unsigned NOT NULL default '0',
timezone int(10) NOT NULL default '0',
PRIMARY KEY (nid),
KEY event_start (event_start)
) TYPE=MyISAM /*!40100 DEFAULT CHARACTER SET utf8 */;"
);
break;
case 'pgsql':
db_query("CREATE TABLE {event} (
nid int NOT NULL default '0',
event_start int NOT NULL default '0',
event_end int NOT NULL default '0',
timezone int NOT NULL default '0',
PRIMARY KEY (nid)
);"
);
break;
}
}
/**
* 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 starting with 1 in each module. The first is mymodule_update_1().
*
* A good rule of thumb is to remove updates older than two major releases of
* Drupal. Never renumber update functions. See hook_update_last_removed() to
* notify Drupal about the removals.
*
* Whenever possible implement both PostgreSQL and MySQL at the same time. If
* PostgreSQL updates are added later, add a new update function which only does
* the PostgreSQL update. Be sure to use comments to describe which updates are
* the same if they do get separated.
*
* 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.
*
* The following examples serve as a quick guide to MySQL to PostgreSQL conversion.
* Usually (but not always!) you will use following SQL statements:
*
* - Adding a key (an index)
* - MySQL: ALTER TABLE {$table} ADD KEY $column ($column)
* - PostgreSQL: CREATE INDEX {$table}_$column_idx ON {$table}($column) // Please note the _idx "extension"
* - Adding a primary key
* - MySQL: ALTER TABLE {$table} ADD PRIMARY KEY $column ($column)
* - PostgreSQL: ALTER TABLE {$table} ADD PRIMARY KEY ($column)
* - Dropping a primary key
* - MySQL: ALTER TABLE {$table} DROP PRIMARY KEY
* - PostgreSQL:ALTER TABLE {$table} DROP CONSTRAINT {$table}_pkey
* - Dropping a column
* - MySQL: ALTER TABLE {$table} DROP $column
* - Postgres: ALTER TABLE {$table} DROP $column
* - Dropping an index
* - MySQL: ALTER TABLE {$table} DROP INDEX $index
* - Postgres:
* - DROP INDEX {$table}_$column_idx // When index was defined by CREATE INDEX
* - ALTER TABLE {$table} DROP CONSTRAINT {$table}_$column_key // In case of UNIQUE($column)
* - Adding a column
* - MySQL: $ret[] = update_sql("ALTER TABLE {vocabulary} ADD tags tinyint(3) unsigned default '0' NOT NULL");
* - Postgres: db_add_column($ret, 'vocabulary', 'tags', 'smallint', array('default' => 0, 'not null' => TRUE));
* - Changing a column
* - MySQL: $ret[] = update_sql("ALTER TABLE {locales_source} CHANGE location location varchar(255) NOT NULL default ''");
* - Postgres: db_change_column($ret, 'locales_source', 'location', 'location', 'varchar(255)', array('not null' => TRUE, 'default' => "''"));
*
* @return An array with the results of the calls to update_sql().
*/
function hook_update_N() {
$ret = array();
switch ($GLOBALS['db_type']) {
case 'pgsql':
db_add_column($ret, 'contact', 'weight', 'smallint', array('not null' => TRUE, 'default' => 0));
db_add_column($ret, 'contact', 'selected', 'smallint', array('not null' => TRUE, 'default' => 0));
break;
case 'mysql':
case 'mysqli':
$ret[] = update_sql("ALTER TABLE {contact} ADD COLUMN weight tinyint(3) NOT NULL DEFAULT 0");
$ret[] = update_sql("ALTER TABLE {contact} ADD COLUMN selected tinyint(1) NOT NULL DEFAULT 0");
break;
}
return $ret;
}
/**
* 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 tables or variables that the module sets.
*
* The uninstall hook will fire when the module gets uninstalled.
*/
function hook_uninstall() {
db_query('DROP TABLE {profile_fields}');
db_query('DROP TABLE {profile_values}');
variable_del('profile_block_author_fields');
}
/**
* 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 "addtogroup hooks".
*/