本文针对文件的传输场景，介绍如何使用PHP SDK V2新增的上传管理器Uploader模块进行文件上传。
注意事项
本文示例代码以华东1（杭州）的地域ID
cn-hangzhou为例，默认使用外网Endpoint，如果您希望通过与OSS同地域的其他阿里云产品访问OSS，请使用内网Endpoint。关于OSS支持的Region与Endpoint的对应关系，请参见OSS地域和访问域名。要进行文件上传，您必须有
oss:PutObject权限。具体操作，请参见为RAM用户授权自定义的权限策略。
方法定义
上传管理器功能简介
PHP SDK V2新增上传管理器Uploader提供了通用的上传接口，隐藏了底层接口的实现细节，提供便捷的文件上传能力。
上传管理器Uploader底层利用分片上传接口，把大文件或者流分成多个较小的分片并发上传，提升上传的性能。
上传管理器Uploader同时提供了断点续传的能力，即在上传过程中，记录已完成的分片状态，如果出现网络中断、程序异常退出等问题导致文件上传失败，甚至重试多次仍无法完成上传，再次上传时，可以通过断点记录文件恢复上传。
上传管理器Uploader的常用方法如下：
final class Uploader
{
...
public function __construct($client, array $args = [])
public function uploadFile(Models\PutObjectRequest $request, string $filepath, array $args = []): Models\UploadResult
public function uploadFrom(Models\PutObjectRequest $request, StreamInterface $stream, array $args = []): Models\UploadResult
...
}请求参数列表
参数名 | 类型 | 说明 |
request | PutObjectRequest | 上传对象的请求参数，和 PutObject 接口的请求参数一致 |
stream | StreamInterface | 需要上传的流 |
filePath | string | 本地文件路径 |
args | array | （可选）配置选项 |
其中，args常用参数说明列举如下：
参数名 | 类型 | 说明 |
part_size | int | 指定分片大小，默认值为 6MiB |
parallel_num | int | 指定上传任务的并发数，默认值为 3。针对的是单次调用的并发限制，而不是全局的并发限制 |
leave_parts_on_error | bool | 当上传失败时，是否保留已上传的分片，默认不保留 |
当使用NewUploader实例化实例时，您可以指定多个配置选项来自定义对象的上传行为。也可以在每次调用上传接口时，指定多个配置选项来自定义每次上传对象的行为。
设置Uploader的配置参数
$u = $client->newUploader(['part_size' => 10 * 1024 * 1024]);设置每次上传请求的配置参数
$u->uploadFile( new Oss\Models\PutObjectRequest( 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);
// 定义要上传的本地文件路径
$filename = "/Users/yourLocalPath/yourFileName"; // 示例文件路径
// 创建上传器实例
$uploader = $client->newUploader();
// 执行分片上传操作
$result = $uploader->uploadFile(
request: new Oss\Models\PutObjectRequest(bucket: $bucket, key: $key), // 创建PutObjectRequest对象，指定Bucket和对象名称
filepath: $filename, // 指定要上传的本地文件路径
);
// 打印分片上传结果
printf(
'multipart upload status code:' . $result->statusCode . PHP_EOL . // HTTP状态码，例如200表示成功
'multipart upload request id:' . $result->requestId . PHP_EOL . // 请求ID，用于调试或追踪请求
'multipart upload result:' . var_export($result, true) . PHP_EOL // 分片上传的详细结果
);
常见使用场景
使用上传管理器设置分片大小和并发数
使用上传管理器上传本地文件流
使用上传管理器设置显示上传进度
相关文档
关于上传管理器的完整示例，请参见GitHub示例。