function hook_requirements

You are here

7 system.api.php hook_requirements($phase)
5 install.php hook_requirements($phase)
6 install.php hook_requirements($phase)
8 system.api.php hook_requirements($phase)

Check installation requirements and do status reporting.

This hook has three closely related uses, determined by the $phase argument:

  • Checking installation requirements ($phase == 'install').
  • Checking update requirements ($phase == 'update').
  • 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 administration configuration page.

Parameters

$phase: The phase in which requirements are checked:

  • install: The module is being installed.
  • update: The module is enabled and update.php is run.
  • runtime: The runtime requirements are being checked and shown on the status report page.

Return value

An associative array where the keys are arbitrary but must be unique (it is suggested to use the module short name as a prefix) and the values are themselves associative arrays with the following elements:

  • title: The name of the requirement.
  • value: The current value (e.g., version, time, level, etc). During install phase, this should only be used for version numbers, do not set it if not applicable.
  • description: The description of the requirement/status.
  • severity: The requirement's result/severity level, one of:

Related topics

16 functions implement hook_requirements()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

color_requirements in modules/color/color.install
Implements hook_requirements().
file_requirements in modules/file/file.install
Implements hook_requirements().
image_requirements in modules/image/image.install
Implements hook_requirements() to check the PHP GD Library.
install_check_requirements in includes/install.core.inc
Checks installation requirements and reports any errors.
install_verify_requirements in includes/install.core.inc
Verifies the requirements for installing Drupal.

... See full list

3 invocations of hook_requirements()
drupal_check_module in includes/install.inc
Checks a module's requirements.
system_status in modules/system/system.admin.inc
Menu callback: displays the site status report. Can also be used as a pure check.
update_check_requirements in ./update.php
Checks update requirements and reports errors and (optionally) warnings.

File

modules/system/system.api.php, line 3053
Hooks provided by Drupal core and the System module.

Code

function hook_requirements($phase) {
  $requirements = array();
  // Ensure translations don't break during installation.
  $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/reports/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. 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/reports/status/run-cron')));

    $requirements['cron']['title'] = $t('Cron maintenance tasks');
  }

  return $requirements;
}

Comments

Calling (e.g.) the url() function within a hook_requirements('install') implementation results in a fatal error, if the module is installed from a profile.

Issue reported here: http://drupal.org/node/1149580

Also see Prevent path functions from using database tables that have not yet been created.

Various pages mention the automated loading of the .module file if hook_requirements is satisfied. The load occurs only for hook_install but not for hook_uninstall or hook_update_*.

Install profiles will fail with a fatal error if your implementation of this hook does not return an array. Even if all your requirements are met, make sure that you return at least an empty array.

@see: http://drupal.org/node/1314616#comment-5483884

You can also set the weight here if you want your requirement to appear at the top of the list at admin/reports/status, like this:

<?php
    $requirements
['super_important_requirement'] = array(
     
'title' => t('Description'),
     
'value' => 'whatever',
     
'severity' => REQUIREMENT_INFO,
     
'weight' => -1000,
    );
?>

The demo here show how to test the version of PHP. Anyway to test the version of jQuery ?