hook_requirements

  1. drupal
    1. 5
    2. 8 system.api.php
    3. 6
    4. 7 system.api.php
Versions
5 – 8 hook_requirements($phase)

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:

Note that you need to use $t = get_t(); to retrieve the appropriate localisation function name (t or st).

Parameters

$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 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, ...).
  • 'description': optional notice for the status report.
  • 'severity': the requirement's result/severity (defaults to OK).

Related topics

Code

documentation/developer/hooks/install.php, line 61

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