跳到主要内容

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.phpflarum 文件调用,是 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/tagsflarum/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.jsoncomposer.lock 文件和 vendor 文件夹,覆盖服务器端即可。建议在每次覆盖前备份服务器。
  • 一些网络主机可能会提供图形化界面使用 Composer。虽说命令行是使用 Compsoer 的最好方式,但如果图形化界面是您唯一的选择,请您根据主机服务商提供的指南来使用图形化界面。

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