PHP包添加版本依赖上限的策略

本文探讨了如何为已发布PHP包的PHP版本依赖添加上限的复杂性。核心问题在于，一旦包版本发布，其`composer.json`中的依赖约束即被固定。在不重写历史或破坏现有安装的情况下，无法干净地追溯性地为已发布版本添加新的PHP版本上限。最佳实践是发布一个新的补丁版本，其中包含更新后的依赖约束，并引导用户升级。

理解PHP包依赖管理中的挑战

在PHP生态系统中，Composer是核心的依赖管理工具。当一个PHP包发布到Packagist.org时，其特定版本（例如v1.0.0）的composer.json文件会被缓存，并作为该版本的权威定义。如果一个包最初发布时，其composer.json中的PHP版本要求为"php": ">=7.0"，这意味着它可以在PHP 7.0及更高版本（包括PHP 8+）上安装。

然而，随着PHP语言的演进，旧版本的包可能并不完全兼容新版本的PHP。例如，一个v1.0.0的包可能在PHP 7上运行良好，但在PHP 8+上会出现不兼容问题。此时，开发者可能希望为v1.0.0版本添加一个PHP版本上限，例如限制其只能在PHP 7上安装（"php": "^7.0"），以避免用户在PHP 8+上安装时遇到问题。

为什么无法“干净地”修改已发布版本的依赖

问题的核心在于Composer和版本控制系统的设计原则：一旦发布，版本即不可变。一个已发布的标签（tag）应该始终指向相同的代码和相同的composer.json。

1. Composer的缓存机制：Packagist和Composer客户端都会缓存已发布版本的信息。如果修改了已发布标签的composer.json，会导致缓存不一致，可能引发难以预料的行为。
2. Git历史的完整性：修改一个已发布的Git标签所指向的提交（commit）或其内容，等同于重写Git历史。这会破坏依赖于此标签的现有用户的工作流，导致他们的本地仓库与远程仓库不一致，甚至可能导致构建失败。
3. 语义化版本控制：语义化版本（Semantic Versioning）的核心原则之一是，一旦发布，版本内容不应改变。任何功能性或兼容性变更都应通过发布新版本来实现。

避免的“非清洁”解决方案

尽管存在一些听起来可能可行的方案，但它们都伴随着严重的副作用，应尽量避免：

1. 发布一个新名称的包：
   • 问题：这会导致包生态系统的碎片化，用户需要迁移到新的包名，且无法保持与旧包的直接升级路径。
2. 删除并重新发布现有标签：
   • 问题：这涉及从Git仓库中删除旧标签，修改代码（添加PHP版本上限），然后以相同的标签名重新创建并推送到远程仓库和Packagist。
   • 后果：
     • 破坏现有安装：已安装此旧版本的用户在执行composer update时可能会遇到问题，因为其本地缓存或锁定文件与新的标签内容不匹配。
     • 历史记录混乱：重写Git历史是高风险操作，尤其对于公共仓库。
     • 维护者声誉受损：这种行为通常被视为不专业的，会影响包维护者的信誉。

推荐的“清洁”解决方案：发布新版本

鉴于上述限制，最标准、最推荐且“清洁”的解决方案是发布一个新的补丁版本（patch version）或次要版本（minor version），其中包含所需的PHP版本依赖上限。

操作步骤：

1. 在开发分支中修改composer.json： 将PHP版本要求从"php": ">=7.0"修改为更严格的约束，例如"php": "^7.0"。

   // 原始 v1.0.0 的 composer.json
   {
       "name": "your/package",
       "require": {
           "php": ">=7.0"
       }
   }
   
   // 新的 v1.0.1 (或 v1.1.0) 的 composer.json
   {
       "name": "your/package",
       "require": {
           "php": "^7.0" // 表示 PHP >=7.0.0 且 <8.0.0
           // 或者 "~7.0.0" 表示 PHP >=7.0.0 且 <7.1.0
       }
   }

   选择^7.0还是~7.0.0取决于你希望支持的PHP 7的具体范围。^7.0通常更常用，因为它允许PHP 7.0、7.1、7.2、7.3、7.4。

2. 提交更改并打上新标签： 将这些更改提交到你的版本控制系统，并打上一个新的语义化版本标签，例如v1.0.1或v1.1.0。

   git commit -m "Add PHP 7 upper bound for compatibility"
   git tag v1.0.1
   git push origin main --tags

3. 将新版本发布到Packagist： Packagist会自动检测新的Git标签并将其索引。

对用户的影响：

• 已安装旧版本的用户：如果用户明确要求"your/package": "1.0.0"，他们将继续使用原始的、无上限的v1.0.0版本。
• 新用户或更新用户：
  • 如果用户要求"your/package": "^1.0"或"your/package": "*"，Composer在解决依赖时会优先选择最新的兼容版本，即v1.0.1（或更新版本）。
  • 在PHP 8+环境下，当这些用户尝试安装或更新到^1.0时，Composer会看到v1.0.1（或更新版本）的composer.json中包含"php": "^7.0"的约束，从而阻止在PHP 8+上安装此版本的包。
• 兼容性问题：对于在PHP 8+上遇到v1.0.0兼容性问题的用户，应引导他们升级到支持PHP 8+的更新版本的包（如果存在），或者在PHP 7环境下使用v1.0.1。

注意事项与最佳实践

• 预先规划依赖：在发布任何包版本之前，仔细考虑其依赖约束，包括PHP版本。如果你的包只兼容特定范围的PHP版本，应从一开始就明确指定上限和下限。
• 语义化版本控制：严格遵循语义化版本控制。任何向后不兼容的更改都应发布为主要版本（major version），功能性更改为次要版本（minor version），bug修复为补丁版本（patch version）。
• 维护多个分支：对于长期维护的包，可以考虑为不同的主要版本维护不同的分支（例如1.x分支和2.x分支），以便在不同版本系列中处理兼容性问题。
• 清晰的文档：在包的文档中明确指出每个版本所支持的PHP版本范围，并提供升级指南。当用户遇到问题时，应建议他们首先检查其PHP版本和包版本是否兼容，并升级到最新版本。

总结

为已发布PHP包的PHP版本依赖添加上限，在不重写历史和不破坏现有安装的前提下，没有“干净”的追溯性方法。最佳实践是接受已发布版本的不可变性，并通过发布包含更新依赖约束的新版本来解决问题。这符合Composer和语义化版本控制的核心原则，并确保了包生态系统的稳定性和可预测性。