本文旨在指导开发者如何在 Drupal 中创建一个简单的自定义页面，显示 "Hello, world"。通过创建一个自定义模块，定义路由，并编写控制器，本文将详细讲解实现过程，并着重强调了命名空间的重要性，帮助读者避免常见的配置错误，最终成功创建并访问自定义页面。
创建自定义模块
首先，我们需要创建一个自定义模块。按照 Drupal 的模块结构，创建一个目录 modules/custom/hello。 在这个目录下，我们需要创建三个文件：hello.info.yml、hello.routing.yml 和 src/Controller/ExampleController.php。
1. hello.info.yml
这个文件定义了模块的基本信息。
name: Hello World Module description: Creates a page showing "Hello World". package: Custom type: module core: 8.x core_version_requirement: ^8 || ^9
2. hello.routing.yml
这个文件定义了访问自定义页面的路由。
hello.my_page:
path: '/hello'
defaults:
_controller: '\Drupal\hello\Controller\ExampleController::myPage'
_title: 'My first page in D9'
requirements:
_permission: 'access content'注意： _controller 的值必须正确指向控制器类和方法。
3. src/Controller/ExampleController.php
这个文件定义了控制器类，负责处理请求并返回页面内容。
<?php
namespace Drupal\hello\Controller;
use Drupal\Core\Controller\ControllerBase;
/**
* Provides route responses for the Example module.
*/
class ExampleController extends ControllerBase {
/**
* Returns a simple page.
*
* @return array
* A simple renderable array.
*/
public function myPage() {
return [
'#markup' => 'Hello, world',
];
}
}关键点：命名空间
确保 hello.routing.yml 文件中 _controller 对应的命名空间与 ExampleController.php 文件中的命名空间完全一致。 这是最容易出错的地方。在这个例子中，两个文件都必须使用 Drupal\hello\Controller 命名空间。如果命名空间不一致，Drupal 将无法找到控制器，导致 "Page not found" 错误。
启用模块并清除缓存
将上述文件放置到正确的目录后，进入 Drupal 后台，找到 "Extend"（模块管理）页面 (/admin/modules)，启用 "Hello World Module" 模块。
启用模块后，必须清除 Drupal 的缓存。进入 "Configuration" -> "Development" -> "Performance" (/admin/config/development/performance)，点击 "Clear all caches"。
访问自定义页面
完成上述步骤后，就可以通过 /hello 路径访问自定义页面了。 如果 Drupal 安装在子目录下，可能需要使用 index.php/hello。
常见问题和解决方案
- "Page not found" 错误： 最常见的原因是命名空间不一致。请仔细检查 hello.routing.yml 和 ExampleController.php 文件中的命名空间是否完全一致。 另外，也要确认模块已经启用，并且缓存已经清除。
- 模块无法启用： 检查 hello.info.yml 文件的格式是否正确。 YAML 文件对缩进非常敏感，请确保缩进正确。
总结
通过以上步骤，我们成功创建了一个简单的 Drupal 自定义页面。 关键在于理解 Drupal 的模块结构、路由定义和控制器编写，特别是要保证命名空间的一致性。 掌握这些基本概念，可以为更复杂的 Drupal 开发打下坚实的基础。 此外，学习 PHP 的面向对象编程（OOP）和 Symfony 框架的基础知识，将有助于更深入地理解和利用 Drupal 的强大功能。
