跳到主要内容

Composer 依赖管理

Flarum 使用 Composer 管理自身依赖和扩展程序。 以下情况，你会用到 Composer：

  • 安装或更新 Flarum
  • 安装、更新或卸载 Flarum 扩展程序

本指南仅让您简要了解 Composer。更多信息请访问 官方文档。

Composer 2.0 版本

1.0 时代，Composer 对内存的过大占用，在共享主机上导致了诸多问题。于是 2020 年 Composer 2.0 发布，这个版本对性能及内存占用问题进行了大幅改进和改善。建议您始终使用 Composer 2.0 版本。

什么是 Composer？#

Composer 是 PHP 的一个依赖管理工具。它允许您声明项目所依赖的代码库，并在项目中为您安装、更新它们。— Composer 介绍

每个 Flarum 站点都由 Flarum 核心和多个 扩展程序 组成。核心和扩展程序也有相应的依赖和不同的版本。

过去，论坛框架的扩展程序管理，通常由用户自行上传压缩包来实现。这种操作看似简单，实则有很多问题：

  • 任何人都可以把压缩文件上传到互联网，恶意程序泛滥，用户安全难以保障。而从 Packagist 这样的统一仓库下载扩展程序，能够大大提高安全性。同时扩展程序的开源代码也可在 GitHub 上完整查看。
  • 假设甲扩展需要使用 v4 版本的某库，而乙扩展需要 v5 版本。如果使用压缩包的管理方案，同一库的不同版本，很可能会产生冲突，导致其中一方被覆盖，进而出现问题。例如二者如果能够同时运行，很可能导致 PHP 崩溃，因为类名不重复声明。
  • 压缩文件可能在自动化部署、自动化测试或节点扩容时出现问题。
  • 无法处理版本冲突和依赖关系。
  • 诚然，我们可以通过替换压缩文件的方式，达到升级扩展程序的目的。但是，如果要升级 Flarum 核心呢？我们如何完美地管理扩展程序，以及核心版本的兼容关系呢？

这些问题，Composer 在解决的同时，也处理得更好。

Flarum 和 Composer#

当您 安装 Flarum 时，您其实做了两件事：

  1. 下载 Flarum 的模板「框架」，包括一个处理 Web 请求的 index.php 文件，一个提供 CLI 服务的 flarum 文件，以及一些 Web 服务器配置和目录设置。框架内容均来自 flarum/flarum GitHub 存储库，实际上并不包含任何 Flarum 运行所必需的代码。
  2. 安装 Flarum 所需的 composer 软件包，即 Flarum 核心，以及随 Flarum 安装的原生扩展。它们由第 1 步中的 index.php 和 flarum 文件调用，是 Flarum 的根本实现。这些软件包均在框架的 composer.json 文件中声明。

你可以执行 composer 命令来更新 Flarum，安装、更新、或卸载扩展程序。每个命令都是不同的，但它们一般都会遵循相同的流程：

  1. 更新 composer.json 文件内容，添加、移除或更新软件包。
  2. 获取所有软件包的版本情况，计算当前需求是否可行。
  3. 如果顺利，下载所有软件包的最新版本，否则恢复 composer.json 原先的内容。

运行 composer.json 命令时，请务必注意控制台输出。如果出现错误，您能在其中找出扩展程序不兼容、PHP 版本不受支持、缺少 PHP 扩展等的原因。

composer.json 文件#

总之，Flarum 站点全部的 Composer 配置都在 composer.json 这一个文件中。您可以查阅 Composer 文档 以了解特定内容。下面是 flarum/flarum 中的 composer.json 文件，我们提供了注释，好让您更好的了解其中的内容。

{    // 下面的内容用于描述当前软件包的元数据。    // 对于论坛管理员来说，这里的内容并不重要。    "name": "flarum/flarum",    "description": "Delightfully simple forum software.",    "type": "project",    "keywords": [        "forum",        "discussion"    ],    "homepage": "https://flarum.org/",    "license": "MIT",    "authors": [        {            "name": "Flarum",            "email": "info@flarum.org",            "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 字段用于描述我们需要什么软件包，以及软件包的版本控制。    // 我们稍后做进一步讨论    "require": {        "flarum/core": "^1.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）    // 它就会使用稳定版本。    // 除非您知道自己在做什么，否则处于生产环境的站点，不应使用测试版本。    "prefer-stable": true}

回到 require 字段中，每个条目都是由 Composer 包名和版本控制组成的键值对。

对于 Flarum 而言，您会经常看到这几种类型的条目：

  • flarum/core 绝不可缺。它的版本控制应当与您想安装的 Flarum 版本显式对应。例如安装 Flarum 1.x 版本，版本控制形式为 ^1.0。
  • 您安装的每一个扩展都会在这里体现。包括随 Flarum 安装的原生扩展： flarum/tags、flarum/suspend 等，以及 通过 Composer 安装 的其他扩展。这些扩展的版本控制均应当是通配符形式（*），通配符意味着安装与您的 Flarum 兼容的版本。除非您有特定目的（如测试 beta 扩展），否则我们不建议您替换通配符。
  • 一些扩展程序和功能可能需要 Flarum 扩展程序以外的 PHP 软件包。例如，您需要 guzzle 库才能使用 Mailgun 邮件驱动。在这种情况下，依赖库用什么版本，相关扩展一般都会有说明。

如何安装 Composer？#

与其他软件一样，安装 Flarum 前，您必须先在服务器上 安装 Composer 。

专用 Web 服务器#

可以按照 Composer 指南 操作。

托管和共享主机#

运行 composer --version 命令检查主机是否预装 Composer。如果没有预装，可以手动安装，过程非常简单，首先 下载 Composer，然后将 phar 文件上传到 Flarum 根目录，最后使用 /你的/php/路径 composer.phar XXX 替换 composer XXX 的命令即可。

温馨提示

网上有些文章会让推荐使用 PHP shell 脚本之类的东西去解决 Composer 的安装问题。如果您不确定自己在做什么或他们在说什么，请小心为妙！未受保护的 Web shell 非常危险。

我如何使用 Composer？#

您需要通过「命令行」Command-line interface (CLI) 使用 Composer。请确保您能通过「SSH」Secure Shell 访问服务器。

安装 Composer 后，您就应该能在 SSH 终端中运行 Composer 命令 composer XXX 了。

性能优化

运行多个命令后，您可以执行 composer dump-autoload -a 缓存 PHP 文件，优化自动加载的性能。

我没用 SSH 权限#

大多数正规服务商都会为共享主机提供 SSH 访问途径。如果您的共享主机没有 SSH 权限，不要沮丧，还有办法可以一试。

  • 使用 Pockethold 之类的替代方法来安装 Flarum。请注意，您仍然需要 Composer 和 SSH 来安装扩展。
  • 在本地计算机上安装 Composer 和 Flarum，然后通过 FTP 将所有文件上传到您的服务器。当需要更新 Flarum，安装、更新或卸载扩展程序时，在本地执行相应的 Composer 命令，然后复制本地 composer.json、composer.lock 文件和 vendor 文件夹，覆盖服务器端即可。建议在每次覆盖前备份服务器。
  • 一些网络主机可能会提供图形化界面使用 Composer。虽说命令行是使用 Compsoer 的最好方式，但如果图形化界面是您唯一的选择，请您根据主机服务商提供的指南来使用图形化界面。

请注意，以上这些解决方法均不受官方支持！官方唯一支持的安装和管理 Flarum 的方式就是 Composer。