新手开发者求助：从零开始开发Drupal 9 Hello World模块

一、基础模块结构搭建 #

1. 在Drupal项目的modules/custom目录下创建hello_world文件夹（自定义模块统一放在custom下，避免与核心/贡献模块冲突）。
2. 新建hello_world.info.yml文件（模块的核心标识文件），写入以下内容：

name: Hello World
type: module
description: '入门级Drupal 9模块，用于输出Hello World内容'
core_version_requirement: ^9 || ^10
package: Custom

• name：模块显示名称
• core_version_requirement：声明兼容Drupal 9/10版本
• package：模块在后台扩展页面的分类

二、配置路由（实现页面访问） #

新建hello_world.routing.yml文件，定义访问路径与处理逻辑：

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

• path：用户访问的URL路径（即你的域名/hello）
• _controller：指定处理请求的PHP类与方法
• _permission：设置访问权限，access content是普通用户默认拥有的权限

三、编写控制器类 #

1. 在hello_world目录下创建src/Controller子目录（Drupal遵循PSR-4命名空间规范，目录结构对应命名空间）。
2. 新建HelloWorldController.php文件，写入以下代码：

<?php

namespace Drupal\hello_world\Controller;

use Drupal\Core\Controller\ControllerBase;

/**
 * 处理Hello World页面请求的控制器
 */
class HelloWorldController extends ControllerBase {

  /**
   * 返回Hello World渲染内容
   *
   * @return array
   *   Drupal渲染数组
   */
  public function hello() {
    return [
      '#markup' => $this->t('Hello World! 这是你的第一个Drupal 9自定义模块。'),
    ];
  }

}

• 继承ControllerBase可以直接使用Drupal的核心工具方法（比如翻译函数t()）
• 返回的数组是Drupal的标准渲染结构，#markup用于输出纯HTML内容

四、启用并测试模块 #

1. 登录Drupal后台，进入「扩展」页面（路径/admin/modules）。
2. 在「Custom」分类下找到「Hello World」模块，勾选后点击「安装」。
3. 访问网站的/hello路径，即可看到输出的Hello World内容。

可选进阶：添加配置功能 #

如果想进一步了解Drupal模块的配置体系，可以添加一个后台配置表单来修改问候语：

1. 新建hello_world.settings.yml（默认配置文件）：

hello_message: 'Hello World!'

2. 新建hello_world.schema.yml（配置结构定义，用于Drupal验证配置）：

hello_world.settings:
  type: config_object
  label: 'Hello World 模块配置'
  mapping:
    hello_message:
      type: string
      label: '问候语内容'

3. 新增路由与菜单入口：
   • 在hello_world.routing.yml中添加配置表单路由：

     hello_world.settings_form:
       path: '/admin/config/system/hello-world'
       defaults:
         _form: '\Drupal\hello_world\Form\HelloWorldSettingsForm'
         _title: 'Hello World 配置'
       requirements:
         _permission: 'administer site configuration'
     

   • 新建hello_world.links.menu.yml添加后台菜单：

     hello_world.settings:
       title: 'Hello World 配置'
       parent: system.admin_config_system
       description: '修改Hello World模块的问候语'
       route_name: hello_world.settings_form
     

4. 编写配置表单类：
   在src/Form目录下新建HelloWorldSettingsForm.php：

   <?php
   
   namespace Drupal\hello_world\Form;
   
   use Drupal\Core\Form\ConfigFormBase;
   use Drupal\Core\Form\FormStateInterface;
   
   /**
    * Hello World模块配置表单
    */
   class HelloWorldSettingsForm extends ConfigFormBase {
   
     /**
      * {@inheritdoc}
      */
     protected function getEditableConfigNames() {
       return ['hello_world.settings'];
     }
   
     /**
      * {@inheritdoc}
      */
     public function getFormId() {
       return 'hello_world_settings_form';
     }
   
     /**
      * {@inheritdoc}
      */
     public function buildForm(array $form, FormStateInterface $form_state) {
       $config = $this->config('hello_world.settings');
   
       $form['hello_message'] = [
         '#type' => 'textfield',
         '#title' => $this->t('问候语'),
         '#default_value' => $config->get('hello_message'),
       ];
   
       return parent::buildForm($form, $form_state);
     }
   
     /**
      * {@inheritdoc}
      */
     public function submitForm(array &$form, FormStateInterface $form_state) {
       $this->config('hello_world.settings')
         ->set('hello_message', $form_state->getValue('hello_message'))
         ->save();
       parent::submitForm($form, $form_state);
     }
   
   }
   

5. 修改控制器方法读取配置：
   更新HelloWorldController.php的hello()方法：

   public function hello() {
     $config = $this->config('hello_world.settings');
     $message = $config->get('hello_message');
     return [
       '#markup' => $this->t($message),
     ];
   }
   

完成后，你可以在后台「配置 > 系统 > Hello World 配置」中修改问候语，访问/hello就能看到更新后的内容。

内容的提问来源于stack exchange，提问作者Medicode