AWS S3 PHP SDK异步传输失败但同步运行正常问题咨询

问题复现 #

日常从S3存储桶向本地设备同步文件时，使用同步代码可正常完成全部文件拉取：

$manager = new \Aws\S3\Transfer($client, $source, $dest);
$manager->transfer();

替换为参照官方文档编写的异步代码后，无任何文件传输动作，既不输出成功提示，也不输出失败提示，整个流程处于无响应状态：

$manager = new \Aws\S3\Transfer($client, $source, $dest);
$promise = $manager->promise();

$promise->then(function () {
    echo 'Done!';
});
$promise->otherwise(function ($reason) {
    echo 'Transfer failed: ';
});

核心原因 #

问题本质是创建的Promise仅完成了回调注册，从未被驱动执行，并非官方文档存在配置遗漏。

• AWS PHP SDK 基于 Guzzle 实现异步能力，Guzzle 的 Promise 采用惰性求值设计：仅在代码中创建 Promise、绑定成功/失败回调，不会自动启动网络请求。整个任务队列没有被触发执行的时机，PHP 脚本会在注册完回调后直接走到退出逻辑，自然不会有实际文件传输动作。
• 官方文档的示例通常为了简化演示，省略了驱动 Promise 执行的必要收尾代码，直接复制片段使用时就会出现“代码写了但完全不跑”的问题。

修正方案 #

在原有异步代码的末尾，显式调用 Promise 的 wait() 方法驱动整个传输流程执行，同时补充原示例遗漏的失败信息打印逻辑，方便异常排查：

$manager = new \Aws\S3\Transfer($client, $source, $dest);
$promise = $manager->promise();

$promise->then(function () {
    echo 'Done!';
});
$promise->otherwise(function ($reason) {
    // 原示例未拼接实际错误原因，补充后可直接定位传输失败的具体异常
    echo 'Transfer failed: ' . $reason->getMessage() . PHP_EOL;
});

// 核心缺失步骤：驱动异步任务队列执行，等待所有传输任务完成
$promise->wait();

补充说明 #

• 这种惰性 Promise 设计是为了支撑高并发批量传输场景：你可以一次性创建多个 S3 传输任务、其他 HTTP 请求任务的 Promise，全部完成回调绑定后，再统一调用一次 wait()，底层会自动通过并发连接跑完全部任务，比逐个同步拉取的传输效率更高。
• 如果需要在异步传输过程中并行处理其他业务逻辑，不用直接阻塞在顶层 Promise 的 wait() 上，但必须保证 PHP 进程退出前，所有已入队的异步任务都被事件循环驱动执行完毕，否则进程会提前终止，无法完成全量文件传输。

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