如何使用OSS PHP SDK V2進行檔案上傳 - Object Storage Service

本文針對檔案的傳輸情境，介紹如何使用PHP SDK V2新增的上傳管理器Uploader模組進行檔案上傳。

注意事項

本文範例程式碼以華東1（杭州）的地區IDcn-hangzhou為例，預設使用外網Endpoint，如果您希望通過與OSS同地區的其他阿里雲產品訪問OSS，請使用內網Endpoint。關於OSS支援的Region與Endpoint的對應關係，請參見OSS地區和訪問網域名稱。
要進行檔案上傳，您必須有oss:PutObject許可權。具體操作，請參見為RAM使用者授予自訂的權限原則。
本文以從環境變數讀取存取憑證為例。更多配置訪問憑證的樣本，請參見PHP配置訪問憑證。

方法定義

上傳管理器功能簡介

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  // 分區上傳的詳細結果
);

常見使用情境

使用上傳管理器設定分區大小和並發數

您可以使用以下代碼設定上傳管理器Uploader的配置參數，設定分區大小和並發數。

<?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);

// 定義分區上傳的相關參數
$partSize = 100 * 1024; // 分區大小，單位為位元組（此處設定為100KB）

// 定義要上傳的本地檔案路徑
$filename = "/Users/yourLocalPath/yourFileName"; // 樣本檔案路徑

// 建立上傳器執行個體
$uploader = $client->newUploader();

// 執行分區上傳操作
$result = $uploader->uploadFile(
    request: new Oss\Models\PutObjectRequest(bucket: $bucket, key: $key), // 建立PutObjectRequest對象，指定Bucket和對象名稱
    filepath: $filename, // 指定要上傳的本地檔案路徑
    args: [ // 選擇性參數，用於自訂分區上傳行為
        'part_size' => $partSize, // 自訂分區大小
        'parallel_num' => 1, // 並發上傳的分區數量
    ]
);

// 列印分區上傳結果
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  // 分區上傳的詳細結果
);

使用上傳管理器上傳本地檔案流

您可以通過以下代碼使用上傳管理器上傳本地檔案流。

<?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);

// 定義分區上傳的相關參數
$partSize = 100 * 1024; // 分區大小，單位為位元組（此處設定為100KB）

// 定義要上傳的本地檔案路徑
$filename = "/Users/yourLocalPath/yourFileName"; // 樣本檔案路徑

// 建立上傳器執行個體
$uploader = $client->newUploader();

// 執行分區上傳操作
// 使用LazyOpenStream以流的形式開啟檔案，避免一次性載入整個檔案到記憶體
$result = $uploader->uploadFrom(
    request: new Oss\Models\PutObjectRequest(
        bucket: $bucket,
        key: $key
    ),
    stream: new \GuzzleHttp\Psr7\LazyOpenStream($filename, 'rb'), // 以唯讀模式開啟檔案流
    args: [
        'part_size' => $partSize, // 自訂分區大小
    ]
);

// 列印上傳結果
printf(
    'upload from status code:' . $result->statusCode . PHP_EOL . // HTTP狀態代碼，例如200表示成功
    'upload from request id:' . $result->requestId . PHP_EOL .   // 請求ID，用於調試或追蹤請求
    'upload from result:' . var_export($result, true) . PHP_EOL  // 上傳的詳細結果
);

使用上傳管理器設定顯示上傳進度

您可以通過以下代碼使用上傳管理器上傳本地檔案時顯示上傳進度。

<?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);

// 定義分區上傳的相關參數
$partSize = 100 * 1024; // 分區大小，單位為位元組（此處設定為100KB）

// 定義要上傳的本地檔案路徑
$filename = "/Users/yourLocalPath/yourFileName"; // 樣本檔案路徑

// 建立上傳器執行個體
$uploader = $client->newUploader();

$request = new \AlibabaCloud\Oss\V2\Models\PutObjectRequest(bucket: $bucket, key: $key);

# 設定上傳進度回呼函數，用於顯示上傳進度
$request->progressFn = function (int $increment, int $transferred, int $total) {
    echo sprintf("已經上傳：%d" . PHP_EOL, $transferred);
    echo sprintf("本次上傳：%d" . PHP_EOL, $increment);
    echo sprintf("資料總共：%d" . PHP_EOL, $total);
    echo '-------------------------------------------' . PHP_EOL;
};

// 執行分區上傳操作
$result = $uploader->uploadFile(request: $request,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  // 分區上傳的詳細結果
);

使用上傳管理器設定上傳回調

如果您希望在檔案上傳後通知應用伺服器，可參考以下程式碼範例。

<?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);

// 定義分區上傳的相關參數
$partSize = 100 * 1024; // 分區大小，單位為位元組（此處設定為100KB）

// 定義要上傳的本地檔案路徑
$filename = "/Users/yourLocalPath/yourFileName"; // 樣本檔案路徑

// 建立上傳器執行個體
$uploader = $client->newUploader();

// 添加x-oss-callback和x-oss-callback-var頭部資訊
// 定義回調地址
 $call_back_url = "http://www.example.com/callback";

// 構造回調參數（callback）：指定回調地址和回調請求體，使用 Base 64 編碼
// 使用預留位置 {var1} 和 {var2} 替代 ${x:var1} 和 ${x:var2}
$callback_body_template = "bucket={bucket}&object={object}&my_var_1={var1}&my_var_2={var2}";
$callback_body_replaced = str_replace(
    ['{bucket}', '{object}', '{var1}', '{var2}'],
    [$bucket, $key, 'value1', 'value2'],
    $callback_body_template
);
$callback = base64_encode(json_encode([
    "callbackUrl" => $call_back_url,
    "callbackBody" => $callback_body_replaced
]));

// 構造自訂變數（callback-var），使用 Base 64 編碼
$callback_var = base64_encode(json_encode([
    "x:var1" => "value1",
    "x:var2" => "value2"
]));

// 執行分區上傳操作
$result = $uploader->uploadFile(
    request: new Oss\Models\PutObjectRequest(
                    bucket: $bucket,
                    key: $key,
                    callback: $callback,
                    callbackVar: $callback_var,), // 建立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  // 分區上傳的詳細結果
);

Object Storage Service：檔案上傳管理器（PHP SDK V2）