Change record status: 
Project: 
Introduced in branch: 
8.x
Introduced in version: 
8.x
Description: 

The signature of hook_help() has changed to use route names instead of paths. The special route name help.page.[module_short_name] is used for the main module page. The current RouteMatch object is also passed in to hook_help() implementations, if more complex logic is needed.

Example - D7:

function dblog_help($path, $arg) {
  switch ($path) {
    case 'admin/help#dblog':
      $output = '';
      $output .= '

' . t('About') . '

'; $output .= '

' . t('The Database logging module logs system events in the Drupal database. For more information, see the online handbook entry for the Database logging module.', array('@dblog' => 'http://drupal.org/documentation/modules/dblog')) . '

'; $output .= '

' . t('Uses') . '

'; $output .= '
'; ... return $output; case 'admin/reports/dblog': return '

' . t('The Database logging module monitors your website, capturing system events in a log (shown here) to be reviewed by an authorized individual at a later time. This log is a list of recorded events containing usage data, performance data, errors, warnings and operational information. It is vital to check the Recent log messages report on a regular basis, as it is often the only way to tell what is going on.') . '

'; }

Example, D8:

use Drupal\Core\Routing\RouteMatchInterface;
...
function dblog_help($route_name, RouteMatchInterface $route_match) {
  switch ($route_name) {
    case 'help.page.dblog':
      $output = '';
      $output .= '

' . t('About') . '

'; $output .= '

' . t('The Database Logging module logs system events in the Drupal database. For more information, see the online handbook entry for the Database Logging module.', array('!dblog' => 'http://drupal.org/documentation/modules/dblog')) . '

'; $output .= '

' . t('Uses') . '

'; ... return $output; case 'dblog.overview': return '

' . t('The Database Logging module monitors your website, capturing system events in a log (shown here) to be reviewed by an authorized individual at a later time. This log is a list of recorded events containing usage data, performance data, errors, warnings and operational information. It is vital to check the Recent log messages report on a regular basis, as it is often the only way to tell what is going on.') . '

'; } }

Note: add a use for RouteMatchInterface if it is not already there.

Impacts: 
Module developers
Updates Done (doc team, etc.)
Online documentation: 
Not done
Theming guide: 
Not done
Module developer documentation: 
Not done
Examples project: 
Not done
Coder Review: 
Not done
Coder Upgrade: 
Not done
Other: 
Other updates done

Comments

Jonathan Webb’s picture

The route help.page.YOUR_MODULE does not need to be added to YOUR_MODULE.routing.yml. Other help routes do need to be added to that file. For example the dblog.overview route is defined as:

dblog.overview:
  path: '/admin/reports/dblog'
  defaults:
    _controller: '\Drupal\dblog\Controller\DbLogController::overview'
    _title: 'Recent log messages'
  requirements:
    _permission: 'access site reports'

See: https://api.drupal.org/api/drupal/core%21modules%21dblog%21dblog.routing...