Drupal模块开发进阶系列教程:从自定义插件到高级主题集成全指南

插件系统先想明白一件事

Drupal 的插件系统干的事情不复杂:按约定发现类、读注解、实例化、交给业务代码调用。区块、字段、视图、图片效果本质都是这一套。

真正要动手前建议先回答三个问题:插件靠什么被发现(注解还是 attributes)、需要哪些依赖、插件定义要不要缓存。这三个问题想清楚了,后面代码基本不会返工。

版本之间这块机制没有根本变化。Drupal 9 到 10、10 到 11 的插件升级问题,九成不在"插件"概念本身,而在旧注解、废弃 API 和主题钩子的清理上。

自定义插件:一个内容处理器的完整链路

目录大致这样放:

custom_module/
├── custom_module.services.yml
├── src/
│   ├── Annotation/CustomContentProcessor.php
│   ├── Plugin/
│   │   ├── CustomContentProcessorBase.php
│   │   ├── CustomContentProcessorInterface.php
│   │   ├── CustomContentProcessorManager.php
│   │   └── ProductSpecProcessor.php

custom_module.services.yml 里注册管理器。注意 class 必须真实存在并继承 DefaultPluginManager,而且不要出现把 plugin.manager.custom_content_processor 自身作为 arguments 注入的写法,那是循环依赖:

services:
  plugin.manager.custom_content_processor:
    class: Drupal\custom_module\Plugin\CustomContentProcessorManager
    parent: default_plugin_manager

管理器构造函数要和父类签名对齐(Drupal 11 额外支持 attribute 声明,这里按 9/10/11 通用写法):

<?php
namespace Drupal\custom_module\Plugin;

use Drupal\Core\Cache\CacheBackendInterface;
use Drupal\Core\Extension\ModuleHandlerInterface;
use Drupal\Core\Plugin\DefaultPluginManager;

final class CustomContentProcessorManager extends DefaultPluginManager {

  public function __construct(
    \Traversable $namespaces,
    CacheBackendInterface $cache_backend,
    ModuleHandlerInterface $module_handler,
  ) {
    parent::__construct(
      'Plugin/CustomContentProcessor',
      $namespaces,
      $module_handler,
      CustomContentProcessorInterface::class,
      'Drupal\custom_module\Annotation\CustomContentProcessor'
    );
    $this->alterInfo('custom_content_processor_info');
    $this->setCacheBackend($cache_backend, 'custom_content_processor_plugins');
  }

}

具体插件用注解标识:

/**
 * @CustomContentProcessor(
 *   id = "product_spec",
 *   label = @Translation("产品规格处理器")
 * )
 */
class ProductSpecProcessor extends CustomContentProcessorBase {
  // 实现接口里的 processContent()。
}

这套链路里我踩过的坑基本就这几个,列出来是因为每一条都真实浪费过时间:

  • 注解类 Annotation\CustomContentProcessor 没写,插件发现直接为空;
  • 命名空间、目录、注解类名三者有一处对不上,也是静默失败;
  • 改了注解之后忘了 drush cr,以为代码没生效;
  • 管理器构造函数参数和 default_plugin_manager 的约定不一致,服务编译期就报错;
  • 插件类忘了实现接口方法,直到调用时才炸。

关于注解和 attributes:Drupal 11 里 attributes 更常见了,但 9/10/11 并存的项目里,先跟团队规范走,别为了追新把整套注解硬换一遍,升级成本通常大于收益。

性能问题多半不是插件机制的锅

插件本身不慢,写法会慢。几条经验:

构造函数只注入真正用到的服务。图省事把 entity_type.manager、database、cache 一股脑塞进去,后续重构时会很痛苦。

请求内重复计算可以用 static 缓存,但记住它只在当前请求有效,别指望它当持久缓存用。

查实体用 entityQuery,一次把 ID 查回来再批量 load。在循环里逐个 load() 就是教科书式的 N+1。

缓存一定要带 cache tags 和 cache contexts。只设 max-age 不设 tags,内容更新了页面不失效,这种 bug 在线上很难排查。

最后是加载时机。能用路由、Block visibility 或 lazy builder 控制的就别全局跑,尤其是别塞回 hook_init 时代的那种全局执行思路。

和主题集成

注册模板:

function custom_module_theme($existing, $type, $theme, $path) {
  return [
    'custom_content_processor' => [
      'variables' => [
        'content' => NULL,
        'processor' => NULL,
        'attributes' => [],
      ],
      'template' => 'custom-content-processor',
    ],
  ];
}

'base hook' => 'block' 不是必写项,只有你确实要继承 block 的模板和变量时才加。模板文件放 templates/custom-content-processor.html.twig。

预处理函数里把 attributes 包成 Attribute 对象,顺便补分类、样式类这些变量:

function custom_module_preprocess_custom_content_processor(&$variables) {
  $variables['attributes'] = new \Drupal\Core\Template\Attribute($variables['attributes'] ?? []);
}

多语言这块别只停留在"注意兼容"。Twig 里用 |t,CSS 尽量写 logical properties,再真开一次 RTL 语言看看布局,很多问题是测出来的不是想出来的。

版本升级:别先写 \Drupal::VERSION 分支

9 到 10 主要是清 deprecated API、升依赖、CKEditor 5 和主题层变化;10 到 11 是 PHP 要求提高、attributes 支持更完善、依赖注入和缓存继续优化。

升级时靠谱的顺序是:

  1. 跑 Upgrade Status,先把硬伤列出来;
  2. 开 deprecation 日志,把运行期触发的旧调用抓干净;
  3. 机械替换交给 Rector,别手工一条条改;
  4. CI 里挂多版本矩阵,别只在自己机器上测;
  5. 能用稳定 API 解决的,就不要写 \Drupal::VERSION 条件分支——分支越多,下一个大版本越难升。

一套代码同时兼容 9/10/11 是有代价的。更现实的策略是:核心逻辑保持兼容,主题和少数服务按版本拆文件。

一个具体例子:产品规格展示

需求很常见:产品节点展示规格参数和相关推荐,要响应式、要多语言。

我的做法:规格整理交给 ProductSpecProcessor 插件,输出 render array;模板用上面注册的 custom_content_processor;相关推荐用 entityQuery 一次查完再批量 load;缓存打节点和产品分类的 tags;测试分两层,Kernel test 测插件发现,Functional test 测页面渲染,性能只看一个指标——每页查询数有没有降下来。

真实项目里最容易出问题的不是插件写不出来,而是插件发现失败、缓存该失效没失效、主题被覆盖后变量对不上、升级时某个 deprecated 调用漏网。把这几类问题提前列进 checklist,比事后排查省时间得多。

联系我们

以专业解您所忧,以诚意不负所托。

长按加微信
长风云团队联系微信二维码
长按关注公众号
长风云公众号二维码