Composer 警告和 composer show 中的 replaced by 字段是最权威替代线索；若无，则查 Packagist 横幅推荐，再按活跃度筛选社区方案；替换前须用 composer depends 查依赖链并全局搜索代码中硬编码引用。

直接看 Composer 的警告信息本身，它往往已经告诉你替代品是谁——别急着搜，先读完那行提示。

查 composer show 确认废弃状态和推荐包名

Composer 在警告里写的 Use other/package instead 是最权威的线索，但有时它藏得深或没写全。用命令挖出来：

composer show vendor/old-package

输出中重点关注两行：

• abandoned : true 或 abandoned : new-vendor/new-package
• replaced by : new-vendor/new-package（如果有）

如果 replaced by 字段存在，优先信它；它来自原作者，不是社区猜测。若字段为空，说明作者没指定替代者，需手动排查。

去 Packagist 页面看“Abandoned”横幅和推荐链接

打开 https://packagist.org/packages/vendor/old-package，页面顶部会有一条醒目的红色横幅：

• 写着 This package is abandoned
• 下方常带一个 Use new-vendor/new-package instead 的可点击链接
• 有些还会标注 This package is a fork of...，指向活跃维护的分支

注意：Packagist 上的推荐链接是人工维护的，比 GitHub README 更可靠——因为后者可能过期，而 Packagist 横幅由维护者主动设置，更新即生效。

当没有官方替代时，按活跃度筛社区方案

比如 guzzlehttp/promises 被废弃，但没写 replaced by，这时不能硬套 Guzzle v7 全量包（可能过度引入依赖）。正确做法是：

• 在 Packagist 搜索关键词 promises，按 last updated 排序，筛出近 6 个月内有 release 的包
• 点进候选包的 GitHub，看 Issues 是否有人提兼容性问题、Pull Requests 是否被及时合入
• 检查其 composer.json 中的 require，确认不引入 PHP 8.3+ 或 ext-uv 这类你环境不支持的硬依赖

常见陷阱：看到高 star 数就选——但 star 可能来自历史项目，实际最近一年零 commit。真正管用的是 Last commit: 2 weeks ago 这种时间戳。

替换前必做：查谁在依赖它，再改 composer.json

别一上来就 composer remove。先跑：

composer depends vendor/old-package

结果可能是：

• your/project（你直接 require 的）→ 直接改 composer.json
• some/other-lib（第三方库依赖它）→ 你无法直接删，得等上游更新，或临时 fork 那个库并 patch 它的 composer.json

改 composer.json 时，不要只换包名，还要同步调整个版本约束：

• 旧包用 "^1.2"，新包可能已升到 "^3.0"，且命名空间/方法签名已变
• 必须全局搜索 use Old\Namespace 和 new OldClass()，否则运行时直接报错

最容易被忽略的点：废弃包往往被当成“工具函数集”硬编码在业务逻辑里，比如 Str::slug() 这种调用——换包后连类名都不同，不 grep 就漏改，上线立刻崩。