How To Notify Site Builders If Something Is Required In Drupal 7

The hook_requirements (API Doc) hook allows you to define custom requirements for modules. The hook can be used to simply notify a site builder with an alert, this is how the Update manager module works. If you have the Update manager module installed and it discovers an out of date module, it’ll display an alert that certain modules need updating.

As another example, in the past I’ve used the hook to display an alert if API login credentials were not available.

You can also define very strict requirements where the installation of a module is aborted when requirements are not met.

In this article we’ll look at how to use the hook for install requirements that aborts an installation if the requirements are not met. Then we’ll look at how to display an alert, similar to how the Update manager displays alerts.

Installation Requirement

Let’s first create an install requirement that aborts the module installation if the site name is not localhost.

1. Implement hook_requirements inside a example.install file.

// example.install
/**
 * Implements hook_requirements().
 */
function example_requirements($phase) {
  $requirements = array();
  $t = get_t();
  // ...
  return $requirements;
}

2. We need our bit of code to only run during the installation phase. Add the following code after $requirements = array();.

  if ($phase == 'install') {
    $site_name = variable_get('site_name');
    if ($site_name != 'localhost') {
      $requirements['site_name'] = array(
        'title' => $t('Site name'),
        'description' => $t('Site name must by localhost.'),
        'value' => check_plain($site_name),
        'severity' => REQUIREMENT_ERROR,
      );
    }
  }

Any $requirements that are inside of if ($phase == 'install') { will be executed during the module installation. If you set the severity to REQUIREMENT_ERROR during the install phrase, then Drupal will abort the installation.

If you try to install the module, and the site name is something other than localhost you’ll get the following error:

Runtime Requirement

The runtime phase works a bit differently than install. The install phase only happens when the module is about to get installed. Whereas, the runtime phase happens while a module is installed.

If we were to update our code example and change if ($phase == 'install') { to if ($phase == 'runtime') {, we would simply get an alert if the site name is not localhost.

  if ($phase == 'runtime') {
    $site_name = variable_get('site_name');
    if ($site_name != 'localhost') {
      $requirements['site_name'] = array(
        'title' => $t('Site name'),
        'description' => $t('Site name must by localhost.'),
        'value' => check_plain($site_name),
        'severity' => REQUIREMENT_ERROR,
      );
    }
  }

If we were to change the site name to something other than localhost we will get the following alert:

And if you go to the status report page you should see the following:

It’s important to note that REQUIREMENT_ERROR works slightly different depending on the phase. When we used it within the install phase, Drupal aborted the installation. But, when you use REQUIREMENT_ERROR within the runtime phase, then Drupal will just display an alert message.

So that’s a basic introduction on how to use hook_requirements. Don’t forget to check out the documentation page for more details on the different phases and severity levels.