如何在PHP中将接口及方法迁移至上游包且不破坏兼容性？

分阶段迁移步骤（全兼容） #

阶段1：Upstream 小版本更新（向后兼容，可在 semver 小版本发布） #

在 Upstream 包中新增目标接口和方法，确保逻辑与 Library 原实现完全一致：

namespace Upstream {
    // 新增与Library同名的接口
    interface NewInterface {}

    class Thing {
        // 新增与Library签名兼容的方法
        public function newMethod(\Upstream\NewInterface $parameter): self {
            return $this; // 与Library原实现逻辑保持一致
        }
    }
}

这一步属于向后兼容的功能新增，完全符合语义化版本（semver）小版本（x.y.z → x.y.z+1）的发布规则，不会破坏任何依赖 Upstream 的现有代码。

阶段2：Library 小版本更新（向后兼容，可在 semver 小版本发布） #

修改 Library 代码，实现与 Upstream 新版本的兼容，并逐步引导用户迁移：

namespace Library {
    /**
     * @deprecated 请使用 \Upstream\NewInterface 替代
     */
    interface NewInterface extends \Upstream\NewInterface {}

    class Thing extends \Upstream\Thing {
        /**
         * @deprecated 请使用 \Upstream\Thing::newMethod() 替代
         */
        public function newMethod(NewInterface $parameter): self {
            parent::newMethod($parameter); // 复用Upstream的实现，确保逻辑一致
            return $this;
        }
    }
}

同时更新 Library 的 composer.json，将 Upstream 的依赖范围调整为 ^x.y.z（x.y.z 为阶段1发布的版本号），确保用户安装 Library 时自动获取兼容的 Upstream 版本。

这一步修改完全兼容现有依赖 Library 的代码：

• 旧代码调用 Library\Thing::newMethod() 并传入 Library\NewInterface 实现类的逻辑依然正常运行；
• 新代码可直接使用 Upstream\NewInterface 和 Upstream\Thing::newMethod()，实现平滑过渡。

阶段3：Library 大版本更新（破坏性变更，需 semver 大版本发布） #

当大部分用户完成迁移后，在 Library 的大版本（x.y.z → x+1.0.0）中移除废弃的接口和方法：

namespace Library {
    class Thing extends \Upstream\Thing {
        // 直接继承父类的newMethod实现
    }
}

关键兼容性保障说明 #

1. 类型兼容性：Library 的 NewInterface 继承 Upstream 同名接口后，所有原 Library\NewInterface 的实现类自动成为 Upstream\NewInterface 的子类，符合里氏替换原则，不会触发类型错误。
2. 方法签名兼容：PHP 7.4+ 支持协变/逆变规则，子类方法的参数类型（Library\NewInterface）比父类（Upstream\NewInterface）更具体（逆变），返回类型（self）比父类（Upstream\Thing）更具体（协变），完全符合语法规则。
3. 过渡阶段兼容：若需支持用户在 Upstream 新旧版本间过渡，可在 Library 中添加条件判断（如 interface_exists()、method_exists()），确保代码在两种环境下都能正常运行。

内容的提问来源于stack exchange，提问作者joachim