Drupal 8 module development #2 – adding basic routing

In the previous article we looked into the very basic job of beginning a module’s port to Drupal 8 and that was to update the module .info file. Next up, we will take a look at updating the routing system create a valid menu entry which will point to the module’s settings page.

In Drupal 7 and previous versions, it was required to implement hook_menu() and return an associative array with a list of parameters which define the menu entry, such as the routing path, the title, access permissions etc. For the Global Redirect module that menu entry for configuring the module looked as such:

/**
 * Implements hook_menu().
 */
function globalredirect_menu() {
  $items['admin/config/system/globalredirect'] = array(
    'title' => 'Global Redirect',
    'description' => 'Choose which features you would like enabled for Global Redirect',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('globalredirect_settings'),
    'access arguments' => array('administer site configuration'),
    'file' => 'globalredirect.admin.inc',
  );

  return $items;
}

With Drupal 8, it is required to update the routing in a dedicated routing file, as well as implementing hook_menu(), so the first order of business would be to create the routing file which takes the format of <module_name>.routing.yml, in our case it will be globalredirect.routing.yml, and we will add the routing information to it:

globalredirect_settings:
  path: '/admin/config/system/globalredirect'
  defaults:
    _form: 'Drupal\globalredirect\Form\GlobalredirectSettingsForm'
  requirements:
    _permission: 'administer site configuration'

The routing declaration begins by specifying the name of this route entry globalredirect_settings, followed by the settings for it. The pattern is used to identify the URL pattern and can actually contain named placeholder parameters like we’ve seen in previous hook_menu() implementations (although they take a different syntax here). The next _form entry specifies the form class which Drupal expects to load for the settings form, and finally the _permission entry specifies the access control to validate the user has specific access.

Followed by routing file, we’ll update the hook_menu()implementation to correlate with the routing entry:

/**
 * Implements hook_menu().
 */
function globalredirect_menu() {
  $items = array();
  $items['globalredirect_settings'] = array(
    'title' => 'Global Redirect',
    'description' => 'Choose which features you would like enabled for Global Redirect.',
    'route_name' => 'globalredirect_settings',
  );
  return $items;
}

As you can see hook_menu() implementation is quite simpler now. While we used the route name for the routing entry in the $items array, it’s not a must and we could’ve specified the path just as well. It’s the route_name array key which actually matters.