如何通過PHP SDK V2上傳檔案 - Object Storage Service

本文介紹如何通過簡單上傳方法將本地檔案快速上傳到OSS，此方法操作簡便，適合快速將本地檔案上傳到雲端儲存。

注意事項

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

範例程式碼

您可以使用以下代碼將本地檔案上傳到目標儲存空間。

<?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], // 對象名稱（必填）
    "file" => ['help' => 'Local path to the file you want to upload.', '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"];       // 對象名稱
$file = $options["file"];     // 本地檔案路徑

// 載入環境變數中的憑證資訊
// 使用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);

// 檢查檔案是否存在
if (!file_exists($file)) {
    echo "Error: The specified file does not exist." . PHP_EOL; // 如果檔案不存在，輸出錯誤資訊並退出
    exit(1);
}

// 開啟檔案並準備上傳
// 使用fopen以唯讀模式開啟檔案，並通過Utils::streamFor將檔案內容轉換為流
$body = Oss\Utils::streamFor(fopen($file, 'r'));

// 建立PutObjectRequest對象，用於上傳檔案
$request = new Oss\Models\PutObjectRequest(bucket: $bucket, key: $key);
$request->body = $body; // 佈建要求體為檔案流

// 執行上傳操作
$result = $client->putObject($request);

// 列印上傳結果
// 輸出HTTP狀態代碼、請求ID和ETag，用於驗證上傳是否成功
printf(
    'status code:' . $result->statusCode . PHP_EOL . // HTTP狀態代碼，例如200表示成功
    'request id:' . $result->requestId . PHP_EOL .   // 請求ID，用於調試或追蹤請求
    'etag:' . $result->etag . PHP_EOL               // 對象的ETag，用於標識對象的唯一性
);

常見使用情境

上傳字串

您可以使用以下代碼將字串上傳至目標儲存空間。

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

// 要上傳的資料內容
$data = 'Hello OSS';

// 建立PutObjectRequest對象，用於上傳對象
$request = new Oss\Models\PutObjectRequest(bucket: $bucket, key: $key);
$request->body = Oss\Utils::streamFor($data); // 佈建要求體為資料流

// 執行上傳操作
$result = $client->putObject($request);

// 列印上傳結果
printf(
    'status code: %s' . PHP_EOL . // HTTP狀態代碼
    'request id: %s' . PHP_EOL .  // 請求ID
    'etag: %s' . PHP_EOL,         // 對象的ETag
    $result->statusCode,
    $result->requestId,
    $result->etag
);

上傳Byte數組

您可以使用以下代碼將Byte數組上傳至目標儲存空間。

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

// 要上傳的byte資料內容
$dataBytes = [72, 101, 108, 108, 111, 32, 79, 83, 83]; // 'Hello OSS' 的 ASCII 值
$dataString = implode(array_map('chr', $dataBytes)); // 將byte數群組轉換為字串

// 建立PutObjectRequest對象，用於上傳對象
$request = new Oss\Models\PutObjectRequest(bucket: $bucket, key: $key);
$request->body = Oss\Utils::streamFor($dataString); // 佈建要求體為資料流

// 執行上傳操作
$result = $client->putObject($request);

// 列印上傳結果
printf(
    'status code: %s' . PHP_EOL . // HTTP狀態代碼
    'request id: %s' . PHP_EOL .  // 請求ID
    'etag: %s' . PHP_EOL,         // 對象的ETag
    $result->statusCode,
    $result->requestId,
    $result->etag
);

上傳網路流

您可以使用以下代碼將網路上傳至目標儲存空間。

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

// 擷取網路檔案的內容
$url = 'https://www.aliyun.com/';
$response = file_get_contents($url);

// 建立PutObjectRequest對象，用於上傳對象
$request = new Oss\Models\PutObjectRequest(bucket: $bucket, key: $key);
$request->body = Oss\Utils::streamFor($response); // 佈建要求體為資料流

// 執行上傳操作
$result = $client->putObject($request);

// 列印上傳結果
printf(
    'status code: %s' . PHP_EOL . // HTTP狀態代碼
    'request id: %s' . PHP_EOL .  // 請求ID
    'etag: %s' . PHP_EOL,         // 對象的ETag
    $result->statusCode,
    $result->requestId,
    $result->etag
);

上傳檔案時顯示上傳進度

您可以使用以下代碼在上傳檔案時設定顯示上傳進度。

<?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";
        exit(1); // 如果必填參數缺失，則退出程式
    }
}

// 從解析的參數中提取值
$region = $options["region"]; // Bucket 所在的地區
$bucket = $options["bucket"]; // Bucket 名稱
$key = $options["key"];       // 對象名稱

// 使用 EnvironmentVariableCredentialsProvider 從環境變數中載入訪問憑證
// 確保環境變數 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET 已正確設定
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// 載入 SDK 的預設配置
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // 設定憑證提供者
$cfg->setRegion($region); // 設定 Bucket 所在的地區

// 如果命令列提供了 endpoint 參數，則使用指定的訪問網域名稱
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

// 建立 OSS 用戶端執行個體
$client = new Oss\Client($cfg);

// 定義要上傳的資料內容
$data = 'Hello OSS';

// 建立 PutObjectRequest 對象，指定 Bucket 和對象 Key
$request = new Oss\Models\PutObjectRequest($bucket, $key);

// 將資料內容轉換為流對象
$request->body = Oss\Utils::streamFor($data);

// 設定上傳進度回呼函數
$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; // 分隔線
};

// 調用 putObject 方法上傳對象
$result = $client->putObject($request);

// 輸出上傳結果
printf(
    'status code: %s' . PHP_EOL, $result->statusCode . // HTTP 響應狀態代碼
    'request id: %s' . PHP_EOL, $result->requestId .   // 請求 ID
    'etag: %s' . PHP_EOL, $result->etag                // 對象的 ETag
);

上傳檔案時設定回呼函數

OSS在完成簡單上傳時可以提供回調（Callback）給應用伺服器。您只需要在發送給OSS的請求中攜帶相應的Callback參數，即可實現回調。

您可以使用以下代碼在上傳檔案時設定回呼函數。

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

// 定義回調伺服器的相關資訊
// 回調URL：接收回調請求的伺服器位址
// 回調Host：回調伺服器的主機名稱
// 回調Body：定義回調內容的模板，支援動態預留位置替換
// 回調BodyType：指定回調內容的格式
$callback = base64_encode(json_encode(array(
    'callbackUrl' => 'yourCallbackServerUrl', // 替換為實際的回調伺服器URL
    'callbackHost' => 'yourCallbackServerHost', // 替換為實際的回調伺服器主機名稱
    'callbackBody' => 'bucket=${bucket}&object=${object}&etag=${etag}&size=${size}&mimeType=${mimeType}&imageInfo.height=${imageInfo.height}&imageInfo.width=${imageInfo.width}&imageInfo.format=${imageInfo.format}&my_var1=${x:var1}&my_var2=${x:var2}',
    'callbackBodyType' => "application/x-www-form-urlencoded", // 回調內容的格式
)));

// 定義自訂變數，用於在回調中傳遞額外資訊
$callbackVar = base64_encode(json_encode(array(
    'x:var1' => "value1", // 自訂變數1
    'x:var2' => 'value2', // 自訂變數2
)));

// 建立PutObjectRequest對象，用於上傳對象
$request = new Oss\Models\PutObjectRequest(bucket: $bucket, key: $key);
$request->callback = $callback; // 設定回調資訊
$request->callbackVar = $callbackVar; // 設定自訂變數

// 執行上傳操作
$result = $client->putObject($request);

// 列印上傳結果
// 輸出HTTP狀態代碼、請求ID以及回調結果，用於驗證上傳是否成功
printf(
    'status code:' . $result->statusCode . PHP_EOL . // HTTP狀態代碼，例如200表示成功
    'request id:' . $result->requestId . PHP_EOL .   // 請求ID，用於調試或追蹤請求
    'callback result:' . var_export($result->callbackResult, true) . PHP_EOL // 回調結果的詳細資料
);

Object Storage Service：簡單上傳（PHP SDK V2）