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: 模块分组名称,具有相同分组名称的模块会在模块管理页面显示在同一分组中,便于查找和管理

Drupal 8 模块开发 自定义模块显示在模块管理页面中

模块 .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 模块的基本文件和目录结构就好了。更进一步的开发学习会在之后的教程中再进行介绍。

看完了?还不过瘾?点此向作者提问
打赏一下,鼓励Ta创作更多好内容!