Bolt CMS扩展开发指南：如何用Composer生态打造你的第一个自定义插件

Bolt CMS扩展开发指南：如何用Composer生态打造你的第一个自定义插件

【免费下载链接】core🧿 Bolt core项目地址: https://gitcode.com/gh_mirrors/core115/core

Bolt CMS 是一款基于 Symfony 和 PHP 的现代开源内容管理系统，它的最大亮点之一就是完全通过 Composer 生态来扩展。本指南带你了解 Bolt CMS 扩展开发的完整流程：一个扩展本质上就是一个 Composer 包，通过composer require安装后，Bolt 会自动发现并加载它。本文将带你从安装、配置到动手编写，打造你的第一个自定义插件。

为什么选择 Composer 方式开发扩展？

传统 CMS 的插件往往需要手动上传、解压、注册，而 Bolt CMS 把扩展做成了标准的 Composer 包，这带来三大好处：

• 版本管理：像管理任何 PHP 依赖一样管理扩展版本，支持升级、回滚、锁定
• 自动发现：Bolt 启动时扫描所有bolt-extension类型的 Composer 包，无需手动注册
• 依赖清晰：扩展之间可以互相声明依赖，冲突一目了然

Bolt 核心自身就依赖了大量 Composer 包（如 Symfony、Doctrine、Twig、API-Platform），这些定义都写在 composer.json 中，你开发扩展时面对的是同一套机制。

💡 项目中自带了几个官方参考扩展供学习，可在 composer.json 的require-dev中看到：acmecorp/reference-extension、bolt/newswidget、bolt/weatherwidget。

扩展是如何被 Bolt 发现的？

理解发现机制，是写好扩展的第一步。核心逻辑在扩展注册表中（src/Extension/ExtensionRegistry.php）：

1. Bolt 通过drupol/composer-packages组件，找出所有type为bolt-extension的 Composer 包
2. 读取每个包composer.json中extra.entrypoint字段——它必须指向你的扩展入口类
3. 将该类实例化并注册，注入容器、查询、Twig 等常用服务

如果包没有声明entrypoint，或类不存在，Bolt 会直接抛出明确报错，所以这两个字段是扩展包最关键的"身份证"。

动手：你的第一个扩展包结构

一个最小可用的 Bolt CMS 扩展包，长这样：

my-extension/ ├── composer.json ├── src/ │ └── MyExtension.php # 入口类（entrypoint） └── config/ ├── config.yaml # 默认配置 ├── services.yaml # 注册 Symfony 服务（可选） └── routes.yaml # 注册路由（可选）

第一步：编写 composer.json

{ "name": "yourname/my-extension", "type": "bolt-extension", "license": "MIT", "require": { "php": ">=8.2" }, "extra": { "entrypoint": "Yourname\\MyExtension\\MyExtension" }, "autoload": { "psr-4": { "Yourname\\MyExtension\\": "src/" } } }

记住两个必填项：type必须是bolt-extension，extra.entrypoint必须指向入口类。

第二步：继承 BaseExtension 编写入口类

Bolt 定义了一个扩展接口（src/Extension/ExtensionInterface.php），要求实现以下方法：

你不需要手动实现接口，直接继承基类即可（src/Extension/BaseExtension.php）：

namespace Yourname\MyExtension; use Bolt\Extension\BaseExtension; class MyExtension extends BaseExtension { public function getName(): string { return 'My Extension'; } public function initialize(): void { // 在这里注册 Widget 或做初始化 } }

基类还内置了大量便利方法（来自src/Extension/ServicesTrait.php）：

• getWidgets()/addWidget()：注册后台仪表盘小组件
• getConfig()：读取扩展的 YAML 配置
• getTwig()、getSession()、getQuery()：直接获取 Twig、Session、内容查询服务
• addTwigNamespace()：把自己的模板目录挂载到 Twig 命名空间
• addListener()：监听 Bolt 的事件

第三步：用 Widget 让扩展"看得见"

Widget 是 Bolt 扩展最常见的产出——在后台仪表盘上插入自定义区块。基类位于src/Widget/BaseWidget.php，你只需继承它，实现getHtml()返回 HTML、实现getTargets()指定插入位置，然后在扩展的initialize()中：

$this->addWidget(new MyWidget());

Widget 会被注入到对应的页面区域（如后台首页、内容列表页上方），这就是src/Widget/Injector/HtmlInjector.php负责完成的工作。

一键安装步骤：从命令行到后台

开发好本地扩展后，接入流程非常简洁：

1. 安装扩展包（本地包用require+ 路径，线上包用包名）

composer require yourname/my-extension

2. 复制服务、路由与默认配置

php bin/console extensions:configure

该命令（实现在src/Command/ExtensionsConfigureCommand.php）会自动：

• 把扩展包里的config/services.yaml、config/routes.yaml复制到项目的config/packages/extension_*.yaml、config/routes/extension_*.yaml
• 用--with-config参数可额外复制默认配置到config/extensions/目录
• 依次调用每个扩展的install()方法
• 清理已卸载扩展的残留文件

3. 在后台验证

登录后台进入Extensions页面（路由为/extensions，由src/Controller/Backend/ExtensionsController.php提供），就能看到扩展名称、版本和依赖列表；点击扩展名可进入详情页查看依赖树。

配置即 YAML：给扩展加上可定制开关

Bolt 扩展的默认配置放在包内config/config.yaml，安装时被复制到项目的config/extensions/目录（例如参考项目的 config/extensions/acmecorp-reference.yaml）。管理员修改的是项目里的副本，升级扩展不会丢失自定义值。

扩展内部通过getConfig()读取配置，它按"主配置 +_local本地覆盖"两份文件合并读取（逻辑见src/Extension/ConfigTrait.php），实现开箱即用又便于定制。

# config/config.yaml（扩展包内默认配置示例） show_logo: true max_items: 5

常见扩展类型速查

在 Bolt 生态中，composer.json的type字段决定了包的角色：

主题包由同一个注册表管理（getThemes()方法），而模板目录可通过基类的addTwigNamespace()自动挂载。

新手避坑清单 ✅

• ❌ 忘了声明type: bolt-extension→ Bolt 根本不会发现你的包
• ❌entrypoint拼错类名 → 启动时直接抛异常
• ❌ 直接改config/extensions/下的配置后又升级扩展 → 学会用_local.yaml做覆盖
• ❌ 在initialize()里做数据库建表等一次性操作 → 这类逻辑应放在install()
• ❌ 忘记跑extensions:configure→ 路由和服务不会注册，页面 404

小结：你的扩展开发路线

1. 创建 Composer 包，type设为bolt-extension并声明entrypoint
2. 继承BaseExtension（src/Extension/BaseExtension.php）编写入口类
3. 用 Widget、Twig 命名空间、事件监听器丰富扩展能力
4. composer require+php bin/console extensions:configure一键接入
5. 在后台 Extensions 页面验证效果

从 Composer 包到一个可见的后台小组件，整个链路只有四步。现在，打开你的编辑器，把第一个 Bolt CMS 自定义插件写出来吧！

【免费下载链接】core🧿 Bolt core项目地址: https://gitcode.com/gh_mirrors/core115/core