PHP OpenStack SDK 物件儲存服務操作完整指南

服務簡介

Swift 是 OpenStack 物件儲存服務，對應 Rackspace Cloud Files。PHP SDK 透過 ObjectStore 服務存取，核心資源為 Container（容器） 與 Object（物件）。

建立連線

<?php
require 'vendor/autoload.php';

use OpenCloud\OpenStack;

$openstack = new OpenStack([
    'username' => 'YOUR_USERNAME',
    'password' => 'YOUR_PASSWORD',  // 或 apiKey
    'authUrl'  => 'https://identity.api.rackspacecloud.com/v2.0/',  // 或 Keystone 端點
    'region'   => 'DFW',
    'tenantId' => 'YOUR_TENANT_ID',  // OpenStack 必填
]);

// 取得 ObjectStore 服務（Cloud Files）
$swift = $openstack->objectStoreService('cloudFiles', 'DFW');
?>

Container（容器）操作

列舉所有容器

<?php
$containers = $swift->containerList();
while ($container = $containers->next()) {
    printf("Container: %-30s Objects: %6d  Bytes: %12d\n",
        $container->name, $container->count, $container->bytes
    );
}
// 同樣支援 $containers->first(), $containers->size()
?>

建立新容器

<?php
$container = $swift->container();
$container->name = 'my-new-container';
// 或直接
$container = $swift->container('my-new-container');
$container->create();  // 同步建立

// 設定容器公開讀取（CDN/靜態網站）
$container->makePublic();  // 設定 X-Container-Read: .r:*
?>

檢索現有容器（含中繼資料）

<?php
$container = $swift->container('existing-container');
// 自動發送 HEAD 請求取得中繼資料
printf("Container: %s\nObjects: %d\nBytes: %d\n",
    $container->name, $container->count, $container->bytes
);
// 存取自訂中繼資料
if ($container->metadata) {
    print_r($container->metadata);
}
?>

刪除容器

<?php
$container = $swift->container('empty-container');
$container->delete();  // 必須為空容器，否則拋出 409 Conflict
?>

更新容器中繼資料

<?php
$container = $swift->container('my-container');
$container->metadata->update_time = time();
$container->metadata->owner = 'team-alpha';
$container->update();  // 或 $container->create() 別名
?>

Object（物件）操作

上傳物件

<?php
$container = $swift->container('assets');

// 從字串
$object = $container->dataObject('hello.txt');
$object->create(['content' => 'Hello World!', 'content_type' => 'text/plain']);

// 從檔案串流（大檔案推薦）
$object = $container->dataObject('large-video.mp4');
$fp = fopen('/path/to/video.mp4', 'r');
$object->create(['content' => $fp, 'content_type' => 'video/mp4']);
fclose($fp);

// 設定自訂中繼資料
$object->metadata->author = 'John Doe';
$object->metadata->version = '1.0';
$object->create();
?>

下載物件

<?php
$object = $container->dataObject('report.pdf');

// 取得內容字串（小檔案）
$content = $object->getContent();

// 串流下載（大檔案，避免記憶體爆炸）
$stream = $object->getStream();
$fp = fopen('/local/path/report.pdf', 'w');
stream_copy_to_stream($stream, $fp);
fclose($fp);
fclose($stream);
?>

列舉容器內物件

<?php
$objects = $container->objectList(['prefix' => 'images/']);  // 可加前綴過濾
while ($object = $objects->next()) {
    printf("%-50s %10d bytes  %s\n",
        $object->name, $object->bytes, $object->lastModified->format('Y-m-d H:i:s')
    );
}
?>

刪除物件

<?php
$object = $container->dataObject('obsolete-file.log');
$object->delete();
?>

複製物件（跨容器/同容器重命名）

<?php
$srcObj = $container->dataObject('source.txt');
$destContainer = $swift->container('backup');
$srcObj->copy($destContainer, 'source-backup.txt');  // 複製到其他容器

// 同容器重命名（複製後刪除原檔）
$srcObj->copy($container, 'renamed.txt');
$srcObj->delete();
?>

大檔案分段上傳（SLO/DLO）

超過 5GB 檔案需使用 Static Large Object (SLO) 或 Dynamic Large Object (DLO)。SDK 封裝 createLargeObject() 自動處理分段。

<?php
$largeObject = $container->dataObject('huge-dataset.tar.gz');
$largeObject->createLargeObject([
    'segment_container' => 'segments',  // 分段儲存容器
    'segment_size'      => 100 * 1024 * 1024,  // 100MB/段
], fopen('/path/to/huge-file', 'r'));
?>

CDN 與靜態網站託管

<?php
// 啟用 CDN
$container->enableCdn();
// 取得 CDN URL
$cdnUrl = $container->getCdnUrl();  // 如 https://cdn.example.com/container/

// 設定靜態網站索引/錯誤頁
$container->metadata->web_index = 'index.html';
$container->metadata->web_error = '404.html';
$container->update();
?>

權限控制（ACL）

<?php
// 容器層級：允許特定 Referer、IP 範圍、用戶
$container->metadata->read_acl = '.r:*,.rlistings';  // 公開讀取+列表
$container->metadata->write_acl = 'user:john';       // 僅 john 可寫入
$container->update();

// 物件層級：臨時授權 URL (TempURL)
$tempUrl = $object->getTempUrl('GET', '+1 hour');  // 1 小時有效下載連結
?>

最佳實踐總結

1. 連線重用：SDK 內建 HTTP Client 連線池，長程序中重用 $openstack 實例。
2. 串流處理：上傳/下載超過 10MB 檔案務必使用串流（fopen resource），避免記憶體耗盡。
3. 錯誤處理：捕獲 OpenCloud\Common\Exceptions\ApiError，依 HTTP 狀態碼實作重試邏輯（429、5xx）。
4. 中繼資料善用：儲存檔案版本、作者、處理狀態等業務屬性，避免額外資料庫查詢。
5. 分段上傳：大檔案自動分段，支援斷點續傳與並行上傳。
6. CDN 整合：靜態資產啟用 CDN，設定 Cache-Control、Expires 優化快取。