Drupal 8 模块开发 1.2 ： 菜单

原文地址：
https://docs.acquia.com/articles/drupal-8-lesson-512-menus  

hook_menu() 和它的回调函数发生了什么？

Drupal 8 里，hook_menu() 系统被拆分为几个 YAML 文件：

Drupal 8 中我们使用 Symfony2 components 处理路径到控制器方法的路由，进行数据显示。

1. 在同一个目录（page_example），创建 page_example.routing.yml 文件。
2. 添加以下代码

   page_example_description:
     path: '/examples/page_example'
     defaults:
       _controller: '\Drupal\page_example\Controller\PageExampleController::description'
     requirements:
       _access: 'TRUE'
   
   page_example_simple:
     path: '/examples/page_example/simple'
     defaults:
       _controller: '\Drupal\page_example\Controller\PageExampleController::simple'
     requirements:
       _permission: 'access simple page'

分析下上面定义的路由 page_example_description ：

• page_example_description
  为 Page example 模块定义一个新路由。
• path
  路由注册的路径，等价于 Drupal 7 中 hook_menu() 内 $items[] 数组的 key。
  需要以斜线开头，详细请查看文档 structure of routes 。
• _controller
  定义路由的路径对应 PageExampleController 控制器的 description 方法。
• requirements
  用户能够访问这个页面所具有的权限。

想使用额外的路由选项，请查看 Structure of routes 。  

构建控制器

Page example 的控制器叫 PageExampleController，里面有个 description() 方法，用户请求这个页面时会被调用。

注意：
把控制器和其他类放在 src/ 目录是 PSR-4 标准的一部分。
Drupal 的其他部分使用了较长的文件路径，使用的是 PSR-0 标准。
如果你看到捐献模块的代码还放在 lib/ 目录，那是 PSR-0，之前的 Drupal 8 进化版本遗留下来的产物，
应该被移动到 src/ 目录。

1. 在模块目录创建放置控制器的目录 src/Controller。
2. 创建控制器文件 PageExampleController.php 。
3. 在文件内声明 PageExampleController 控制器类

   <?php
   
   /**
   * @file
   * Contains \Drupal\page_example\Controller\PageExampleController.
   */
   
   namespace Drupal\page_example\Controller;
   
   use Drupal\Core\Url;
   
   /**
   * Controller routines for page example routes.
   */
   class PageExampleController {
     /**
      * Constructs a page with descriptive content.
      *
      * Our router maps this method to the path 'examples/page_example'.
      */
     public function description() {
       $simple_url = Url::fromRoute('page_example_simple');
       $simple_link = \Drupal::l(t('simple page'), $simple_url);
   
       $arguments_url = Url::fromRoute('page_example_description', [], ['absolute' => TRUE]);
       $arguments_link = \Drupal::l(t('arguments page'), $arguments_url);
   
       $build = [
         '#markup' => t(
           '<p>The Page example module provides two pages, "simple" and "arguments".</p>'
             . '<p>The !simple_link just returns a renderable array for display.</p>'
             . '<p>The !arguments_link takes two arguments and displays them, as in @arguments_url</p>',
           [
             '!simple_link' => $simple_link,
             '!arguments_link' => $arguments_link,
             '@arguments_url' => $arguments_url->toString()
           ]
         ),
       ];
   
       return $build;
     }
   
     /**
      * Constructs a simple page.
      *
      * The router _controller callback, maps the path 'examples/page_example/simple'
      * to this method.
      *
      * _controller callbacks return a renderable array for the content area of the
      * page. The theme system will later render and surround the content with the
      * appropriate blocks, navigation, and styling.
      */
     public function simple() {
       return [
         '#markup' => '<p>' . t('Simple page: The quick brown fox jumps over the lazy dog.') . '</p>',
       ];
     }
   
   }

  PageExampleController 类里有两个函数：

• description() 函数
  返回一个类似 Drupal 7 的可渲染数组，这里用到了 URL::fromRoute 方法。
• simple() 函数
  返回了一个 HTML 的标记。

出于实用性，这是我们把文本显示在目标 URL 内所需要写的最少代码。
代码中的第 8 行定义了类的名字空间，名字空间允许在其他地方使用这个类。

PHP 中的名字空间
“尽管名字空间可以包含任何有效的 PHP 代码，但名字空间只会影响以下代码类型：
类（包括 abstracts 和 traits 类），接口，函数和常量。
名字空间使用 namespace 关键字进行声明。
包含名字空间的文件必须在文件的顶部、任何其他代码（declare 关键字除外）之前进行名字空间的声明。”
Defining Namespaces

声明了名字空间后，我们便可以通过 use 操作符引入这些类，以便使用它们的方法。

使用 use 操作符
“使用别名引用外部的一个完全限定名是名字空间的重要特征。
这类似 unix 文件系统中为文件或目录创建符号链接一样。
PHP 中别名通过 use 操作符完成。”
Using namespaces: Aliasing/Importing

怎么知道名字空间和 use 操作符的路径？

其实，名字空间就是文件所在位置的路径，之后使用这个作为 use 操作符使用的别名。

类文件类似这样：

namespace Drupal\page_example\Controller;

另一个要使用它的文件这样：

use Drupal\page_example\Controller

之后你就可以使用 Controller 目录下的文件了。  

菜单链接

Drupal 7 中使用 hook_menu() 构建菜单链接。现在不再这么处理了，而是通过 yml 文件配置。  

构建链接
我们现在在 Drupal 管理界面的 Reports 菜单下创建一个菜单链接。

1. 在模块目录创建 page_example.links.menu.yml
2. 追加代码到文件内

   page_example.description:
     title: 'Page Example'
     route_name: page_example_description
     parent: system.admin_reports
   page_example.simple:
     title: 'Simple - no arguments'
     route_name: page_example_simple
     parent: system.admin_reports

首先我们定义了菜单链接的机器名，接下来是菜单的标题和菜单使用的路由（机器名），最后是菜单的 parent（决定菜单的位置）。  

parent 的值是父菜单链接机器名，确定这个需要对 *.links.menu.yml 进行些调查。管理界面菜单定义在核心 System 模块内，因此需要查看 system.links.menu.yml 文件来确定这个值。  

现在清空缓存，打开 http://example.com/admin/reports 页面，你会看到添加的链接。  

清空缓存
如果要通过命令行重建 Drupal 8 站点、清空缓存，需要使用最新版本的 drush： drush rc