PHP 依赖管理实战指南：从 Composer 到 PEAR（php-the-right-way 最佳实践详解）

• 文档
• 教程

本篇基于 php-the-right-way 仓库的"依赖管理（Dependency Management）"章节展开。任何 PHP 项目都几乎不可能只依赖语言本身——框架、类库与组件构成了项目的依赖体系。读完本文，你将掌握 PHP 两大包管理系统（Composer 与 PEAR）的完整使用流程：从安装 Composer、编写composer.json、理解composer.lock与版本约束，到用 Composer 接管 PEAR 依赖的进阶方案，并了解依赖更新通知与安全漏洞检查的实战手段。

在 PHP 生态中，有大量类库、框架和组件可供选择，一个真实项目往往同时使用多个——这些就是项目的依赖（dependencies）。在很长一段时间里，PHP 缺少一套可靠的依赖管理方案：即便你手动管理第三方代码，还必须自行操心自动加载（autoloading）。如今这个问题已经彻底解决，而答案就写在 php-the-right-way 仓库的_posts/04-01-01-Dependency-Management.md及其两个子章节中：Composer 与 PEAR。

两大包管理系统：Composer 与 PEAR 的定位

当前 PHP 生态存在两个主要的包管理系统——Composer与PEAR。Composer 是目前 PHP 社区使用最广泛的包管理器；而 PEAR 在很长一段时期内曾是 PHP 的首要包管理器。即使你从未实际使用过 PEAR，了解它的历史依然有价值，因为你仍然可能在老项目或文档中遇到它的身影。

• Composer：现代 PHP 项目的事实标准，负责按项目粒度管理依赖，并将依赖自动下载到本地vendor/目录、自动生成自动加载器。其详细内容见仓库子章节_posts/04-02-01-Composer-and-Packagist.md。
• PEAR：历史悠久的包管理器，以"全局安装"为特点，要求包作者按特定结构打包。详细内容见_posts/04-03-01-PEAR.md。

从仓库结构可以看到，这两个子章节通过 front matter 中的anchor字段（composer_and_packagist、pear）被父章节引用，并由index.html遍历site.posts统一渲染为单页文档——这本身就体现了"按主题组织、交叉引用"的知识组织方式。

Composer：PHP 推荐的依赖管理器

Composer 是 php-the-right-way 推荐的 PHP 依赖管理器。它的工作模型可以类比为 Node.js 世界的NPM或 Ruby 世界的Bundler：把项目的依赖声明写入composer.json文件，然后用几条简单命令，Composer 就会自动下载依赖并为你配置好自动加载（autoloading）。

composer.json声明文件 +vendor/依赖目录 + 自动生成的vendor/autoload.php，构成了 Composer 依赖管理的三个核心部件：

1. 声明：composer.json描述"项目需要什么、在什么版本范围内"；
2. 解析与下载：Composer 依据声明解析版本冲突，把包下载到vendor/目录；
3. 自动加载：vendor/autoload.php负责按需加载这些依赖，避免手写require。

如何安装 Composer

最安全的方式是遵循官方安装指引，它会校验安装器是否损坏或被篡改，然后安装一个composer.phar二进制文件到你的当前工作目录。php-the-right-way 建议将 Composer全局安装（例如放到/usr/local/bin）：

mv composer.phar /usr/local/bin/composer

若因权限不足而失败，请用sudo前缀重试：sudo mv composer.phar /usr/local/bin/composer。

安装位置决定了调用方式：

• 局部安装：php composer.phar <命令>
• 全局安装：直接composer <命令>

Windows 上的安装

Windows 用户最简单的方案是使用 ComposerSetup 安装器：它执行全局安装，并自动配置$PATH，使你在任意目录的命令行中都能直接调用composer。

定义与安装依赖

Composer 在composer.json文件中跟踪项目的依赖。你可以手工编辑它，也可以让 Composer 自己管理。composer require命令用于添加项目依赖；若项目尚无composer.json，该命令会自动创建。例如添加 Twig 模板引擎作为依赖：

composer require twig/twig:^2.0

其中twig/twig是"厂商名/包名"（vendor/package），^2.0是版本约束——含义是">= 2.0.0 且 < 3.0.0"，保证兼容 2.x 系列的新版本。更稳妥的做法是只写composer require twig/twig，让 Composer 按最新稳定版自动选择并写入约束。

另一种方式是composer init：它通过交互式问答引导你生成一份完整的composer.json。无论哪种方式，一旦composer.json就绪，就可以让 Composer 下载并安装依赖到vendor/目录。这一命令同样适用于你从他人处下载、已自带composer.json的项目：

composer install

接下来，在你的应用主 PHP 文件中加入一行，让 PHP 使用 Composer 的自动加载器加载项目依赖：

<?php require 'vendor/autoload.php';

之后你就可以直接使用项目依赖，它们会被按需自动加载，无需再手工require每一个文件。

与自动加载标准的衔接

Composer 的自动加载能力与 PHP 的命名空间规范密不可分。仓库章节_posts/03-03-01-Namespaces.md指出：PHP 社区开发者众多，不同类库可能使用相同的类名，在同一个命名空间下会发生冲突；命名空间（namespace）如同操作系统的目录一样将代码"分门别类"，让同名类可以共存。Composer 生成自动加载器时所依赖的正是PSR-4标准——它把类名、文件路径与命名空间约定统一起来，实现"即插即用"。2014 年 10 月 PHP-FIG 已废弃旧的PSR-0自动加载标准，但两者仍可使用；新应用或新包建议直接采用 PSR-4。这也解释了为什么composer.json中的autoload配置常常以 PSR-4 规则声明。

更新依赖：composer.lock 的作用

Composer 会在首次执行composer install时生成composer.lock文件，精确记录每个包当时下载到的确切版本。如果你与他人共享项目，务必把composer.lock一并提交，这样对方执行composer install时获得的将是与你这完全一致的版本。

• 更新依赖使用composer update；
• 部署时不要使用composer update，只使用composer install，否则生产环境可能得到与开发环境不同的包版本。

composer.lock的价值在"弹性版本约束"下体现得最充分。例如约束~1.8表示"高于1.8.0，但低于2.0.x-dev"；你也可以使用*通配符，如1.8.*。在这种灵活约束下，composer update会把所有依赖升级到满足你设定限制的最新版本。版本约束语义速览：

依赖更新通知

为了及时获知新版本发布，可以订阅libraries.io——该 Web 服务能够监控依赖并发送更新提醒。它直接读取你的依赖清单（如composer.json/composer.lock），当某个依赖发布新版本时通过邮件等渠道通知你。

检查依赖的安全问题

Local PHP Security Checker是一个命令行工具，它会检查你的composer.lock文件，并告诉你是否需要更新某些依赖以修复已知安全漏洞。它比对的是官方安全公告数据库，因此可以集成进持续集成（CI）流程，在每次构建时自动扫描依赖的安全状态——这是生产项目依赖管理中不可省略的一环。

用 Composer 管理全局依赖

Composer 同样可以处理全局依赖及其可执行文件，用法很直接：在命令前加上global前缀。例如要全局安装 PHPUnit：

composer global require phpunit/phpunit

该命令会创建~/.composer目录存放全局依赖。要让已安装包的二进制文件随处可用，需要把~/.composer/vendor/bin目录加入你的$PATH环境变量。

PEAR：老牌全局包管理器

PEAR 是部分 PHP 开发者钟爱的资深包管理器。它的行为与 Composer 类似，但存在一些显著差异：

• 要求包具有特定结构：包作者必须预先为 PEAR 准备打包结构；未按 PEAR 规范准备的项目无法使用。
• 全局安装：包一经安装，即可被该服务器上的所有项目共享。若多个项目依赖同一个包的同一版本，这是优点；但若两个项目对版本要求冲突，就可能引发问题。

安装 PEAR

下载.phar安装器并执行即可完成安装。PEAR 官方文档对不同操作系统都有详细安装说明。如果你使用 Linux，也可以借助发行版自带的包管理器——例如 Debian 和 Ubuntu 提供php-pear的 apt 包。

安装一个包

若包已收录在 PEAR 官方包列表中，直接指定官方名称安装：

pear install foo

若包托管在**其他渠道（channel）**上，则需要先discover（发现）该渠道，并在安装时指定它：

pear channel-discover <channel-url> pear install <channel>/<package>

用 Composer 接管 PEAR 依赖

如果你已经在使用 Composer，又希望安装一些 PEAR 代码，Composer 同样可以管理 PEAR 依赖。需要特别注意的是：Composer 2 已不再直接支持 PEAR 仓库，你必须手动添加一个 repository 来安装 PEAR 包。示例composer.json：

{ "repositories": [ { "type": "package", "package": { "name": "pear2/pear2-http-request", "version": "2.5.1", "dist": { "url": "https://github.com/pear2/HTTP_Request/archive/refs/heads/master.zip", "type": "zip" } } } ], "require": { "pear2/pear2-http-request": "*" }, "autoload": { "psr-4": {"PEAR2\\HTTP\\": "vendor/pear2/pear2-http-request/src/HTTP/"} } }

各配置段的职责如下：

1. "repositories"：告诉 Composer"初始化"（PEAR 术语即discover）这个仓库。这里使用type: "package"直接内联定义包元数据，是 Composer 2 下接入 PEAR 包的推荐方式；
2. "require"：包名以pear-channel/package的形式前缀。pear前缀是硬编码的，以避免冲突——例如某个 PEAR 渠道名可能与另一个包的厂商名相同，通过pear前缀 + 渠道短名（或完整 URL）即可无歧义地定位包所在渠道；
3. "autoload"：声明 PSR-4 自动加载规则，把PEAR2\HTTP\命名空间映射到包源码目录。

安装完成后，包会出现在你的vendor目录中，并通过 Composer 自动加载器直接可用：

vendor/pear2/pear2-http-request/pear2/HTTP/Request.php

在业务代码中使用该 PEAR 包时，只需像使用任何 Composer 依赖一样引用：

<?php require __DIR__ . '/vendor/autoload.php'; use PEAR2\HTTP\Request; $request = new Request();

实战建议：把依赖管理纳入日常工作流

结合本章节内容，可以沉淀出一套可执行的 PHP 依赖管理规范：

1. 新项目一律使用 Composer，通过composer init生成规范的composer.json，并在主入口require 'vendor/autoload.php'；
2. composer.lock必须纳入版本控制，开发、测试、生产全程用composer install保证版本一致；只有主动升级时才执行composer update；
3. 版本约束保持弹性但不过度：用^、~、*合理表达兼容范围，让依赖可以在安全范围内自动升级；
4. 全局工具（如 PHPUnit）用composer global require安装，并把~/.composer/vendor/bin加入$PATH；
5. 定期做安全体检：借助 Local PHP Security Checker 扫描composer.lock，配合 libraries.io 的更新通知，第一时间发现需要修复的依赖；
6. 遗留的 PEAR 包不必弃之不用：通过repositories+require+autoload（PSR-4）三段式配置，让 Composer 2 统一接管 PEAR 依赖，享受统一的自动加载与版本管理。

进一步阅读

本章节在仓库中的原始素材与相关章节：

• 章节总览：_posts/04-01-01-Dependency-Management.md
• Composer 与 Packagist 详解：_posts/04-02-01-Composer-and-Packagist.md
• PEAR 详解：_posts/04-03-01-PEAR.md
• 命名空间与 PSR-4 自动加载标准：_posts/03-03-01-Namespaces.md
• 标准 PHP 库（SPL）等语言基础：_posts/03-04-01-Standard-PHP-Library.md

依赖管理是 PHP 工程化的地基：声明依赖、锁定版本、自动加载、安全扫描，这套由 Composer 承载的流程，能让你的项目在数不清的类库海洋中既保持整洁，又始终可控。

• 文档
• 教程