本文针对文件的传输场景，介绍如何使用PHP SDK V2新增的下载管理器Downloader模块进行文件下载。
注意事项
本文示例代码以华东1（杭州）的地域ID
cn-hangzhou为例，默认使用外网Endpoint，如果您希望通过与OSS同地域的其他阿里云产品访问OSS，请使用内网Endpoint。关于OSS支持的Region与Endpoint的对应关系，请参见OSS地域和访问域名。本文以从环境变量读取访问凭证为例。更多配置访问凭证的示例，请参见PHP配置访问凭证。
要进行文件下载，您必须有
oss:GetObject权限。具体操作，请参见为RAM用户授予自定义的权限策略。
方法定义
下载管理器功能简介
PHP SDK V2新增下载管理器Downloader提供了通用的下载接口，隐藏了底层接口的实现细节，提供便捷的文件下载能力。
下载管理器Downloader底层利用范围下载，把文件自动分成多个较小的分片进行并发下载，提升下载的性能。
下载管理器Downloader同时提供了断点续传的能力，即在下载过程中，记录已完成的分片状态，如果出现网络中断、程序异常退出等问题导致文件下载失败，甚至重试多次仍无法完成下载，再次下载时，可以通过断点记录文件恢复下载。
下载管理器Downloader的常用方法如下：
final class Downloader
{
...
public function __construct($client, array $args = [])
public function downloadFile(Models\GetObjectRequest $request, string $filepath, array $args = []): Models\DownloadResult
public function downloadTo(Models\GetObjectRequest $request, \Psr\Http\Message\StreamInterface $stream, array $args = []): Models\DownloadResult
}请求参数列表
参数名 | 类型 | 说明 |
request | GetObjectRequest | 下载对象的请求参数，和 GetObject 接口的 请求参数一致 |
filePath | string | 本地文件路径 |
args | array | （可选）配置选项 |
其中，args常用参数说明列举如下：
参数名 | 类型 | 说明 |
part_size | int | 指定分片大小，默认值为 6MiB |
parallel_num | int | 指定下载任务的并发数，默认值为 3。针对的是单次调用的并发限制，而不是全局的并发限制 |
use_temp_file | bool | 下载文件时，是否使用临时文件，默认使用。先下载到临时文件上，当成功后，再重命名为目标文件 |
当使用Downloader实例化实例时，您可以指定多个配置选项来自定义对象的下载行为。也可以在每次调用下载接口时，指定多个配置选项来自定义每次下载对象的行为。
设置Downloader的配置参数：
$d = $client->newDownloader(['part_size' => 10 * 1024 * 1024]);设置每次下载请求的配置参数：
$d->downloadFile( new Oss\Models\GetObjectRequest( bucket: 'bucket', key: 'key' ), filepath: '/local/dir/example', args: ['part_size' => 10 * 1024 * 1024] );
示例代码
您可以使用以下代码将存储空间中的文件下载到本地。
<?php
// 引入自动加载文件，确保依赖库能够正确加载
require_once __DIR__ . '/../vendor/autoload.php';
use AlibabaCloud\Oss\V2 as Oss;
// 定义命令行参数的描述信息
$optsdesc = [
"region" => ['help' => 'The region in which the bucket is located.', 'required' => True], // Bucket所在的地域（必填）
"endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False], // 访问域名（可选）
"bucket" => ['help' => 'The name of the bucket', 'required' => True], // Bucket名称（必填）
"key" => ['help' => 'The name of the object', 'required' => True], // 对象名称（必填）
];
// 将参数描述转换为getopt所需的长选项格式
// 每个参数后面加上":"表示该参数需要值
$longopts = \array_map(function ($key) {
return "$key:";
}, array_keys($optsdesc));
// 解析命令行参数
$options = getopt("", $longopts);
// 验证必填参数是否存在
foreach ($optsdesc as $key => $value) {
if ($value['required'] === True && empty($options[$key])) {
$help = $value['help']; // 获取参数的帮助信息
echo "Error: the following arguments are required: --$key, $help" . PHP_EOL;
exit(1); // 如果必填参数缺失，则退出程序
}
}
// 从解析的参数中提取值
$region = $options["region"]; // Bucket所在的地域
$bucket = $options["bucket"]; // Bucket名称
$key = $options["key"]; // 对象名称
// 加载环境变量中的凭证信息
// 使用EnvironmentVariableCredentialsProvider从环境变量中读取Access Key ID和Access Key Secret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();
// 使用SDK的默认配置
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // 设置凭证提供者
$cfg->setRegion($region); // 设置Bucket所在的地域
if (isset($options["endpoint"])) {
$cfg->setEndpoint($options["endpoint"]); // 如果提供了访问域名，则设置endpoint
}
// 创建OSS客户端实例
$client = new Oss\Client($cfg);
// 创建下载器实例
$downloader = $client->newDownloader();
// 定义本地文件路径，用于保存下载的内容
$filename = "/Users/yourLocalPath/yourFileName"; // 示例文件路径
touch($filename); // 创建一个空文件，确保文件存在
// 执行分片下载操作
$result = $downloader->downloadFile(
new Oss\Models\GetObjectRequest(
bucket: $bucket,
key: $key
),
$filename
);
// 打印下载结果
printf(
'download status code:' . $result->statusCode . PHP_EOL .
'download request id:' . $result->requestId . PHP_EOL .
'download result:' . var_export($result, true) . PHP_EOL
);
常见使用场景
相关文档
关于下载管理器的完整示例，请参见GitHub示例。