第17章 Flarum 指南：使用 Composer 管理依赖与扩展

Version: 2.xComposer Flarum 使用名为 Composer 的工具来管理其依赖项和扩展。 若你想执行以下操作，就需要使用 Composer： 通过命令行安装或更新 Flarum 通过命令行安装、更新或移除 Flarum 扩展 本指南简要介绍了 Composer。我们强烈建议查阅官方文档以获取更多详细信息。 共享主机（Shared Hosting） 在共享主机环境中，建议使用扩展管理器（Extension Manager）替代 Composer。扩展管理器是 Composer 的图形化界面，允许你在无需 SSH 访问权限的情况下安装、更新和移除扩展。 你可以通过归档文件直接安装 Flarum，无需使用 Composer。在预装了扩展管理器的情况下，请查阅安装指南获取更多信息。 什么是 Composer？ Composer 是 PHP 的依赖管理工具。它允许你声明项目所依赖的库，并自动为你管理（安装/更新）它们。—— Composer 简介 每个 Flarum 安装主要包含 Flarum 核心及一组扩展。它们各自拥有独立的依赖项和发布版本。 早年间，论坛框架通过让用户上传包含扩展代码的 zip 文件来管理扩展。这听起来很简单，但问题很快就会暴露出来： 从互联网随机上传 zip 文件通常是个坏主意。强制要求扩展从 Packagist 等中央源下载，虽然稍微繁琐些，但能更有效地防止恶意代码被植入，并确保免费/公开扩展的源代码在 GitHub 上可用。 假设扩展 A 需要某个库的 v4 版本，而扩展 B 需要同一库的 v5 版本。在使用基于 zip 的方案中，其中一个依赖可能会覆盖另一个，导致各种不一致的问题；或者两者同时尝试运行，这会导致 PHP 崩溃（你不能两次声明同一个类）。 若试图实现部署自动化、运行自动化测试或扩展至多服务器节点，zip 文件会带来诸多麻烦。 没有好的方法能确保冲突的扩展版本无法安装，或系统 PHP 版本及扩展要求已得到满足。 当然，我们可以通过替换 zip 文件来升级扩展。但那 Flarum 核心呢？我们如何确保扩展可以声明其兼容的核心版本？ Composer 解决了所有这些及其他更多问题！ Flarum 与 Composer 当你安装 Flarum 时，实际上是在做两件事： 下载 Flarum 的样板“骨架”。这包括处理 Web 请求的 index.php 文件、提供 CLI 的 flarum 文件，以及大量 Web 服务器配置和文件夹设置。这些内容取自 flarum/flarum GitHub 仓库，并不包含 Flarum 运行所需的具体代码。 安装 Flarum 必需的 Composer 软件包，即 Flarum 核心及若干内置扩展。这些由步骤 1 中的 index.php 和 flarum 文件调用，构成了 Flarum 的实现部分。它们在骨架中包含的 composer.json 文件里指定。 当你想要更新 Flarum 或添加/更新/移除扩展时，需通过执行 Composer 命令来完成。各命令有所不同，但所有命令都遵循相同的一般流程： 更新 composer.json 文件以添加/移除/更新软件包。 进行大量计算，尽量获取所有事物的最新兼容版本，或找出所请求配置为何不可行的原因。 若一切正常，下载所有需要更新的软件包的新版本。若有异常，则还原 composer.json 的更改。 运行 composer.json 相关命令时，务必留意输出信息。如果发生错误，通常会告知原因是扩展不兼容、PHP 版本不支持、缺少 PHP 扩展或其他问题。 composer.json 文件 如上所述，你的 Flarum 站点的所有 Composer 配置都包含在 composer.json 文件中。你可以查阅 Composer 文档了解具体模式，现在让我们来看看 flarum/flarum 中一个带有注释的 composer.json： {
// 以下部分主要是关于包的元数据。
// 对论坛管理员来说，这部分内容并不重要。
"name": "flarum/flarum",
"description": "简洁易用的论坛软件。",
"type": "project",
"keywords": [
"forum",
"discussion"
],
"homepage": "https://flarum.org/",
"license": "MIT",
"authors": [
{
"name": "Flarum",
"email": "[email protected]",
"homepage": "https://flarum.org/team"
}
],
"support": {
"issues": "https://github.com/flarum/core/issues",
"source": "https://github.com/flarum/flarum",
"docs": "https://flarum.org/docs/"
},
// 元数据部分结束

// 接下来是我们要重点关注的部分。
// 它列出了我们需要的包，以及每个包对应的版本。
// 我们稍后会详细讨论这部分内容。
"require": {
"flarum/core": "^2.0",
"flarum/approval": "*",
"flarum/bbcode": "*",
"flarum/emoji": "*",
"flarum/lang-english": "*",
"flarum/flags": "*",
"flarum/likes": "*",
"flarum/lock": "*",
"flarum/markdown": "*",
"flarum/mentions": "*",
"flarum/nicknames": "*",
"flarum/pusher": "*",
"flarum/statistics": "*",
"flarum/sticky": "*",
"flarum/subscriptions": "*",
"flarum/suspend": "*",
"flarum/tags": "*"
},

// 各种 Composer 配置项。这里列出的是合理的默认值。
// 可访问 https://getcomposer.org/doc/06-config.md 查看选项列表。
"config": {
"preferred-install": "dist",
"sort-packages": true
},

// 如果 Composer 找到包的稳定版本（非 dev、alpha 或 beta 版本），
// 就应该使用它。一般来说，除非你清楚自己在做什么，否则
// 生产环境网站不应该运行 beta 软件。
"prefer-stable": true
}
我们重点来看 require 部分。每个条目由一个 composer 包名和一个版本号字符串组成。关于版本号字符串的更多细节，可以查阅 composer 相关文档。 对于 Flarum 项目，根安装目录的 require 部分通常会出现以下几类条目：

必须有一个 flarum/core 条目，并且要写明确切的版本号，对应你想安装的大版本。比如要安装 Flarum 2.x，就写 ^2.0。

每个已安装的扩展都应有对应条目。部分内置扩展默认包含在内（如 flarum/tags、flarum/suspend 等），其他扩展则通过 composer 命令添加。除非有特殊原因（比如测试某个包的 beta 版本），我们建议扩展的版本号统一用星号（*），意思是「安装与我的 flarum/core 兼容的最新版本」。

有些扩展或功能可能需要非 Flarum 扩展的 PHP 包。例如使用 Mailgun 邮件驱动需要 guzzle 库。这类情况下，相关扩展或功能的文档会说明该用哪个版本号。

如何安装 Composer？

和其他软件一样，Composer 需要先安装在运行 Flarum 的服务器上，具体方式取决于你的主机类型。

独立服务器

按 Composer 官方指南的推荐方式安装即可。

托管 / 共享主机

如果主机没有预装 Composer（可通过运行 composer --version 检查），可以手动安装：把 composer.phar 上传到你的目录，之后所有文档里写的 composer COMMAND 命令，都用 /path/to/your/php7 composer.phar COMMAND 的方式执行。

网上有些文章会提到用 PHP shell 之类的工具。如果你不清楚自己在做什么、也不明白它们在说什么——务必小心！未加防护的 web shell 极其危险。

如何使用 Composer？

你需要通过命令行界面（CLI）使用 Composer，请确保能通过 SSH 连接到服务器。

安装好 Composer 后，就可以在 SSH 终端里通过 composer COMMAND 的方式执行 Composer 命令了。

大多数命令执行完后，建议运行一次 composer dump-autoload -a。这本质上是为 PHP 文件生成缓存，让它们运行得更快。