Drupal 8 模块开发入门教程

本文将详细说明如何从零开始，开发出一个非常简单的 Drupal 8 模块，为理解 Drupal 8 模块和后续的开发学习打下必要的基础。

确定模块名称

进行 Drupal 8 模块开发的第一步，就是为模块取一个好名称。不仅要能够望文生义，模块名称还需要遵循以下规范：

• 必须以字母开头
• 只能包含小写字母和下划线，不能包含空格
• 必须唯一，不能与网站上使用的其它模块重名
• 不能使用如下名称：src, lib, vendor, assets, css, files, images, js, misc, templates, includes, fixtures, drupal 等等

遵循以上规范，我们使用 hello_world 作为将要开发的模块的名称。

创建模块目录

名称确定之后，便可以开始创建模块目录。在 Drupal 7 中，自定义模块都是推荐放置于 sites/all/modules/custom 目录下。在 Drupal 8 中，依然可以使用此路径。另外，Drupal 8 中还可以放置层级较浅的 modules/custom 目录下。（custom 目录不存在，自选创建即可）

说明：相比较而言，第一个路径因为是放置于 sites 目录下，所以备份和升级时会更方便一点，而第二个路径只有二级比较浅，访问起来会方便一点，但备份和升级时需要注意保留。

这里我们尝试一下 Drupal 8 提供的新路径 modules/custom，在其中为我们将开发的 hello_world 模块创建目录，完整的路径则是 modules/custom/hello_world

使用 .info.yml 文件声明模块信息

在 modules/custom/hello_world 目录下，创建文件 hello_world.info.yml，并填入以下信息

name: Hello World
description: A custom Drupal 8 module.
package: Custom

type: module
core: 8.x

以上各行文本的作用说明如下：

• name: 模块的易读名称，将在模块管理等页面进行显示
• description: 模块功能介绍或简单说明
• type: 类型，因为是开发模块，所以固定填写 module
• core: 内核版本，这里固定填写 8.x
• package: 模块分组名称，具有相同分组名称的模块会在模块管理页面显示在同一分组中，便于查找和管理

模块 .info.yml 文件的更多属性及对应值的写法可参考《Drupal 8 模块 .info.yml 文件完整模版》

添加控制器文件

接下来，在 hello_world 目录下，创建目录结构 src/Controller，并在 Controller 目录下新建文件 HelloWorldController.php，完整路径即 hello_world/src/Controller/HelloWorldController.php

将以下内容编写到 HelloWorldController.php 文件中：

<?php

// 声明命名空间，格式为 Drupal\[module_name]\Controller
namespace Drupal\hello_world\Controller;

// 导入内核提供的控制器基础类
use Drupal\Core\Controller\ControllerBase;

/**
 * Returns responses for Hello World module routes.
 */
class HelloWorldController extends ControllerBase {

  public function content() {
    return array(
      '#markup' => 'Hello, World!',
    );
  }

}

此控制器文件目前并不执行任何操作，只是先将其创建出来，提供一个可以返回内容的 content() 方法。

之后，我们会通过 .routing.yml 文件添加新页面，并在其中调用控制器中的 content() 方法输出内容。

使用 .routing.yml 文件添加新页面路径

在 hello_world 模块目录下，新建文件 hello_world.routing.yml 并在其中写入以下内容：

hello_world.content:
  path: '/hello'
  defaults:
    _title: 'Hello World'
    _controller: '\Drupal\hello_world\Controller\HelloWorldController::content'
  requirements:
    _permission: 'access content'

从字面上不难看出，此 .routing.yml 文件定义的内容有：

• path：向系统中添加一个页面路径 /hello
• _title：将此页面的标题设置为 Hello World
• _controller：调用指定的控制器方法。示例则是调用 HelloWorldController 中的 content() 方法
• _permission: 访问此路径所需要的权限。示例设置为需要有 access content （访问内容）权限

至此，到模块管理页面启用 Hello World 模块，然后访问 /hello 路径，便可以打开标题为 Hello World, 内容为 Hello, World! 的页面了。

更多 .routing.yml 文件结构可参考《Structure of routes》

小结

虽然目前这个 Hello World 模块的功能还非常简单，但这一节主要掌握好如何创建模块，熟悉 Drupal 8 模块的基本文件和目录结构就好了。更进一步的开发学习会在之后的教程中再进行介绍。