Composer如何为依赖包打补丁_应用自定义修复与修改

27次阅读

为Composer依赖包打补丁可通过cweagans/composer-patches插件实现，先安装插件，再创建.patch文件记录修改，最后在composer.json的extra中配置patches，运行composer install/update即可自动应用补丁，适用于修复bug、添加功能或解决兼容性问题。

当你的项目依赖的某个Composer包出现bug、缺少某个你急需的功能，或者与你当前环境存在兼容性问题，但官方又迟迟不发布更新时，为依赖包打补丁（patch）就成了一个非常实用的解决方案。它允许你在不修改vendor目录下的原始文件，也不需要fork整个仓库的情况下，对第三方包进行自定义的修复或修改，从而确保你的项目能够顺利运行或集成特定功能。这本质上是一种“临时”或“局部”的定制，帮助你快速解决燃眉之急。

解决方案

要为Composer依赖包打补丁，最常用且推荐的方式是使用cweagans/composer-patches这个插件。它能让你在composer.json中定义补丁，并在composer install或composer update时自动应用这些补丁。

步骤如下：

安装补丁插件： 在你的项目根目录运行：
```
composer require cweagans/composer-patches
```
这会将插件添加到你的composer.json的require-dev或require部分，并安装到你的项目中。
创建补丁文件： 假设你需要修改vendor/some/package中的一个文件。
- 首先，找到你想修改的原始文件，并对其进行修改（可以直接在vendor目录下修改，但这只是为了生成补丁，最终会被覆盖）。
- 然后，你需要生成一个cweagans/composer-patches0文件，这个文件记录了你的修改内容。最常见的方法是使用cweagans/composer-patches1。
  - 如果你已经将vendor/some/package克隆到本地，并且知道原始版本和你的修改版本，你可以使用cweagans/composer-patches3。
  - 更实际的做法是：
    1. 确保vendor/some/package是干净的（即没有你的任何修改）。
    2. 将vendor/some/package复制一份到临时目录，比如cweagans/composer-patches6。
    3. 在vendor/some/package中进行你需要的修改。
    4. 使用cweagans/composer-patches8来生成补丁文件。
    5. 删除cweagans/composer-patches6。
  - 示例补丁文件内容 (composer.json0)：
```
--- a/vendor/some/package/src/SomeClass.php +++ b/vendor/some/package/src/SomeClass.php @@ -10,7 +10,7 @@  class SomeClass  {      public function doSomething()      { -        // Original problematic code +        // My custom fixed code          return 'old value';      }  }
```
- 建议将所有的补丁文件放在项目根目录下的一个单独目录中，例如composer.json1。

配置composer.json： 在你的composer.json文件中，添加一个composer.json4部分，并在其中定义composer.json5。

{     "require": {         "php": "^8.1",         "some/package": "^1.0"     },     "extra": {         "patches": {             "some/package": {                 "Fix for critical bug in doSomething method": "patches/my_fix_for_some_package.patch",                 "Add new feature X": "patches/add_feature_x.patch"             }         },         "patches-ignore": {             "some/package": [                 "Fix for critical bug in doSomething method"             ]         }     } }

composer.json5：键是需要打补丁的包名（例如composer.json7）。值是一个对象，其中键是补丁的描述（方便理解），值是补丁文件的路径。
composer.json8（可选）：如果你想暂时禁用某个补丁，可以将其添加到这里。

应用补丁： 保存composer.json后，运行：
```
composer install
```
或者，如果你已经安装了依赖，但修改了补丁配置，则运行：
```
composer update
```
cweagans/composer-patches插件会在Composer安装或更新依赖后，自动检测并应用你定义的补丁。如果补丁应用成功，你会在控制台看到相应的提示。

为什么我们需要为Composer依赖包打补丁？

说实话，没有人喜欢给依赖包打补丁，这总感觉像是在给别人的代码“动手术”。但很多时候，你就是会遇到那种情况，不得不这么做。

上游Bug未修复： 这是最常见的原因。你发现了一个关键的bug，它影响了你的业务逻辑或导致了安全漏洞，但包的维护者可能还没意识到，或者修复需要时间。等待官方发布版本，可能意味着你的项目要停滞，或者面临风险。打个补丁，可以让你立即解决问题，继续推进开发。
定制化需求： 某些时候，一个依赖包的功能几乎满足你的需求，但就是差那么一点点。例如，它可能没有提供一个你需要的钩子（hook）或配置选项。为了不fork整个项目并维护一个自己的版本，一个简单的补丁就能让你添加所需的功能，同时还能继续享受上游的更新。
兼容性问题： 你可能在使用一个较旧的包，但你的PHP版本或框架版本已经更新了，导致包的某些部分不再兼容。一个小的补丁可以桥接这些兼容性鸿沟，让你暂时不用升级或替换整个包。
紧急安全修复： 发现了一个严重的安全漏洞，官方补丁还没出来，或者你无法立即升级整个包。这时，一个针对性的安全补丁可以为你争取时间，保护你的系统。
临时性解决方案： 有些问题可能只是暂时的，比如某个第三方API的行为临时改变了，或者你正在等待一个更全面的重构。打个补丁，能让你在短期内保持系统稳定运行。

我个人觉得，打补丁是一种务实的妥协。它不是最佳实践，但却是很多实际开发场景下的“救命稻草”。它让我们在面对外部依赖的不可控性时，多了一层掌控感。

如何创建和管理有效的补丁文件？

创建和管理补丁文件，其实有它自己的一套“艺术”和最佳实践。一个好的补丁，应该清晰、专注，并且易于维护。

图改改

在线修改图片文字

455

查看详情

创建补丁文件的技巧：

基于Git Diff： 这是最推荐的方式。
- 方法一（推荐）：
  1. 确保你的vendor/some/package目录是干净的（没有本地修改）。
  2. 使用composer install2将目标包的仓库克隆到本地一个临时目录（比如composer install3）。
  3. 切换到你项目composer install4中该包对应的版本（composer install5）。
  4. 在这个composer install3中进行你的修改。
  5. 生成补丁：composer install7（如果你只修改了几个文件，可以指定文件路径）。
  6. 将composer install8移动到你的项目composer.json1目录下。
- 方法二（更直接，但需小心）：
  1. 在vendor/some/package目录中，使用composer update1确保当前没有未提交的修改。
  2. 直接修改vendor/some/package中的文件。
  3. 在项目根目录运行composer update3。
  4. 重要： 生成补丁后，记得撤销你在vendor目录中的修改，例如composer update5，因为Composer会重新安装这些文件。
使用composer update6命令行工具： 如果你不想涉及Git，或者目标包没有Git仓库，可以使用composer update6命令。
- 复制原始文件或目录到临时位置。
- 修改原始文件或目录。
- 使用composer update8生成补丁。
- composer update9表示统一格式，composer.json0表示显示C函数名（对PHP文件没用，但无害），composer.json1表示递归比较目录，composer.json2表示将不存在的文件视为空文件。

补丁文件格式： 补丁文件通常采用统一差异格式 (Unified Diff Format)。它清晰地展示了哪些行被删除（以composer.json3开头）、哪些行被添加（以composer.json4开头），以及上下文行（以空格开头）。

--- a/path/to/original/file.php    # 原始文件路径 +++ b/path/to/modified/file.php    # 修改后文件路径 @@ -10,7 +10,7 @@  # 块头信息：-号表示原始文件从第10行开始的7行，+号表示修改后文件从第10行开始的7行  class MyClass  {      public function someMethod()      { -        // Old problematic line +        // New fixed line          return true;      }  }

管理补丁文件的最佳实践：

专用目录： 将所有补丁文件放在一个专门的目录中，例如composer.json1。这使得它们易于查找和管理。
清晰的命名： 补丁文件名应该具有描述性，例如composer.json6。
详细的描述： 在composer.json中，给每个补丁提供一个清晰的描述，说明它解决了什么问题或添加了什么功能。这对于团队成员和未来的你都非常有帮助。
版本控制： 补丁文件本身应该被纳入你的项目版本控制系统（Git等），这样它们可以随着你的代码一起被管理和部署。
专注性： 尽量让每个补丁只解决一个问题或添加一个功能。避免一个补丁文件包含多个不相关的修改，这样会增加维护难度。
考虑上游贡献： 如果你的补丁解决了上游包的一个通用bug或添加了一个有用的功能，强烈建议你将它贡献回上游仓库。这不仅能帮助社区，也能减轻你自己的维护负担。一旦你的修改被合并并发布，你就可以移除相应的补丁了。

打补丁可能带来的风险与替代方案是什么？

打补丁虽然能解决燃眉之急，但它并非没有代价。任何对第三方代码的非官方修改都可能带来一些风险，同时，也有其他的策略可以考虑。

打补丁的风险：

维护负担增加： 这是最直接的风险。你的补丁是针对特定版本的包文件生成的。当上游包发布新版本时，你的补丁很可能会与新版本产生冲突，导致补丁应用失败，或者更糟糕的是，静默地应用但产生意想不到的副作用。这意味着每次更新依赖，你都可能需要重新检查、调整甚至重写补丁。
升级困难： 由于上述维护负担，你可能会因为害怕补丁冲突而推迟依赖包的升级。这可能导致你的项目错过重要的安全更新、性能改进或新功能。
代码可读性降低： 补丁机制将修改逻辑从实际代码中分离出来，增加了理解项目整体行为的难度。新的开发者可能不会立即意识到某个依赖包有自定义补丁。
“技术债”积累： 如果补丁是临时性的，但长期没有被移除或贡献回上游，它就可能变成一种技术债，随着时间推移越来越难以管理。
隐藏真实问题： 有时候，打补丁只是治标不治本。它可能掩盖了更深层次的设计问题，或者表明你使用的包本身并不适合你的需求。

替代方案：

面对需要修改依赖包的情况，除了打补丁，我们还有其他一些策略可以考虑：

贡献回上游 (Upstream Contribution)： 这是最理想的解决方案。如果你的修改是通用性的bug修复、性能优化或有价值的新功能，将其提交到原始仓库。一旦被接受并发布，你就可以完全移除你的补丁，并享受官方维护带来的好处。这需要一些时间和沟通，但从长远来看，是最可持续的方式。
Fork并维护自己的版本： 如果你的修改非常大，或者你对包有持续的、项目特定的定制需求，那么fork原始仓库，并维护一个自己的版本可能是更好的选择。
- 你可以将你的fork作为私有Composer包发布（例如，使用私有Satis/Packagist），或者直接通过Git仓库地址引用。
- 缺点： 你将承担所有维护责任，包括合并上游更新、处理兼容性问题等。
使用事件监听器、钩子或装饰器模式： 许多现代框架和库都提供了丰富的扩展点，允许你在不修改核心代码的情况下改变其行为。
- 事件（Events）/钩子（Hooks）： 在特定操作发生时触发你的自定义代码。
- 服务装饰器（Service Decorators）： 在依赖注入容器中，你可以“装饰”一个服务，用你自己的实现包裹它，从而在不修改原始类的情况下改变其行为。这在Symfony等框架中很常见。
- 继承/组合： 如果包的类设计允许，你可以继承或组合它们，然后覆盖或扩展你需要的方法。
寻找替代包： 如果一个包频繁出现问题，或者其设计与你的项目需求严重不符，那么可能需要考虑寻找一个功能相似但更适合你的项目、维护更活跃的替代包。
与维护者沟通： 在考虑任何修改之前，先与包的维护者沟通。他们可能已经意识到了问题，或者有更好的解决方案。一个友好的交流可能比你自己动手打补丁更有效。