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 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 localisation you should for example use $t = get_t() to retrieve the appropriate localisation 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.

Parameters

$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 value

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:

Related topics

7 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
install_check_requirements in ./install.php
Check installation requirements and report any errors.
system_requirements in modules/system/system.install
Implementation of hook_requirements().
unicode_requirements in includes/unicode.inc
Return Unicode library status and errors.
update_check_requirements in ./update.php
Check update requirements and report any errors.

... See full list

4 invocations of hook_requirements()
drupal_check_module in includes/install.inc
Check a module's requirements.
drupal_check_profile in includes/install.inc
Check a profile'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
Check update requirements and report any errors.

File

developer/hooks/install.php, line 72
Documentation for the installation and update system.

Code

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;
}

Comments

Note that this hook must go into your .install file, in order to block the installation of the module unless requirements exist. If it's in your .module file, only the runtime phase will execute. A lot of contrib modules get this wrong.

Using D6 here, I found that the order of functions in my .install file was significant.

It seemed that hook_requirements($phase) needed to go before hook_schema() and hook_install().

If I didn't have the functions in that order code that created a directory in files/ failed.

After the first time a module is enabled (thus passing the requirements check), Drupal installs the module and marks it as such. From that point on, even if you disable the module and re-enable it, hook_requirements will never be invoked again on install, unless the module explicitly has an uninstall hook and is manually uninstalled before it is re-installed and rechecked for requirements.

Essentially, for the install phase, this hook assumes that the requirements established in the hook will never change once the module is installed. If the requirements-checking, non-uninstallable module is initially installed and then disabled, and down the line some of the requirements are no longer met (e.g. other module updates), the module will never get another chance to check requirements again before being re-enabled.

A quick-and-dirty workaround is to go to the system database table and set the schema_version field of the module to -1, thus effectively marking it as "never installed".