本章节介绍如何通过 TOS PHP SDK 来完成常见的操作，如创建存储桶，上传、下载和删除对象等。

前提条件 #

向 TOS 发送 HTTP/HTTPS 请求之前，必须先创建 TOS 客户端（即创建 TosClient 实例），具体步骤，请参见初始化客户端。

客户端通用示例 #

使用 TosClient 进行接口调用操作完成后，没有异常抛出，则表明操作成功；若抛出异常，则说明操作失败，此时应从 SDK 自定义异常中获取详细的错误信息。以下代码展示了使用 TosClient 的通用方式。

<?php

// 假设使用 composer 安装
require_once __DIR__ . '/vendor/autoload.php';

use Tos\TosClient;
use Tos\Exception\TosClientException;
use Tos\Exception\TosServerException;
use Tos\Model\PutObjectInput;

$region = 'your region';
$endpoint = 'your endpoint';
// 从环境变量中获取访问密钥
$ak = getenv('TOS_ACCESS_KEY'); 
$sk = getenv('TOS_SECRET_KEY'); 
$bucket = 'bucket-test';
$key = 'key-test';
$data = 'hello world';

try {
    // 创建 TOS 客户端
    $client = new TosClient([
        'region' => $region,
        'endpoint' => $endpoint,
        'ak' => $ak,
        'sk' => $sk,
    ]);
       
    // 调用接口请求 TOS 服务端，如上传对象
    $input = new PutObjectInput($bucket, $key, $data);
    $output = $client->putObject($input);
    // 操作成功，获取请求结果
    echo 'put object succeed, request id: ' . $output->getRequestId() . PHP_EOL;
    echo $output->getETag() . PHP_EOL;
    echo $output->getHashCrc64ecma() . PHP_EOL;
} catch (TosClientException $ex) {
    // 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
    echo 'put object failed, message: ' . $ex->getMessage() . PHP_EOL;
} catch (TosServerException $ex) {
    // 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
    echo 'put object failed, code: ' . $ex->getErrorCode() . PHP_EOL;
    echo $ex->getRequestId() . PHP_EOL;
    echo $ex->getStatusCode() . PHP_EOL;
    echo $ex->getMessage() . PHP_EOL;
} catch (\Exception $ex) {
    // 作为兜底捕获其他异常，一般不会执行到这里
    echo 'put object unexpected exception, message: ' . $ex->getMessage() . PHP_EOL;
}

创建桶 #

桶是 TOS 的全局命名空间，相当于数据的容器、文件系统的根目录，可以存储若干对象。以下代码展示如何新建一个桶。

<?php

// 假设使用 composer 安装
require_once __DIR__ . '/vendor/autoload.php';

use Tos\TosClient;
use Tos\Exception\TosClientException;
use Tos\Exception\TosServerException;
use Tos\Model\CreateBucketInput;

try {
    $client = new TosClient([
        'region' => 'your region',
        'endpoint' => 'your endpoint',
        // 从环境变量中获取访问密钥
        'ak' => getenv('TOS_ACCESS_KEY'),
        'sk' => getenv('TOS_SECRET_KEY'),
    ]);
       
    $input = new CreateBucketInput('bucket-test');
    $output = $client->createBucket($input);

    echo $output->getRequestId() . PHP_EOL;
} catch (TosClientException $ex) {
    echo $ex->getMessage() . PHP_EOL;
} catch (TosServerException $ex) {
    echo $ex->getRequestId() . PHP_EOL;
    echo $ex->getStatusCode() . PHP_EOL;
    echo $ex->getErrorCode() . PHP_EOL;
}

上传对象 #

以下代码展示如何上传对象至 TOS 的桶中。

<?php

// 假设使用 composer 安装
require_once __DIR__ . '/vendor/autoload.php';

use Tos\TosClient;
use Tos\Exception\TosClientException;
use Tos\Exception\TosServerException;
use Tos\Model\PutObjectInput;

try {
    $client = new TosClient([
        'region' => 'your region',
        'endpoint' => 'your endpoint',
        // 从环境变量中获取访问密钥
        'ak' => getenv('TOS_ACCESS_KEY'),
        'sk' => getenv('TOS_SECRET_KEY'),
    ]);
       
    $input = new PutObjectInput('bucket-test',  'key-test',  'hello world');
    $output = $client->putObject($input);

    echo $output->getRequestId() . PHP_EOL;
} catch (TosClientException $ex) {
    echo $ex->getMessage() . PHP_EOL;
} catch (TosServerException $ex) {
    echo $ex->getRequestId() . PHP_EOL;
    echo $ex->getStatusCode() . PHP_EOL;
    echo $ex->getErrorCode() . PHP_EOL;
}

下载对象 #

以下代码展示如何从 TOS 的桶中下载指定对象并读取数据。

<?php

// 假设使用 composer 安装
require_once __DIR__ . '/vendor/autoload.php';

use Tos\TosClient;
use Tos\Exception\TosClientException;
use Tos\Exception\TosServerException;
use Tos\Model\GetObjectInput;

$output = null;
try {
    $client = new TosClient([
        'region' => 'your region',
        'endpoint' => 'your endpoint',
        // 从环境变量中获取访问密钥
        'ak' => getenv('TOS_ACCESS_KEY'),
        'sk' => getenv('TOS_SECRET_KEY'),
    ]);
       
    $input = new GetObjectInput('bucket-test',  'key-test');
    $output = $client->getObject($input);

    echo $output->getRequestId() . PHP_EOL;
    // 读取对象数据
    echo $output->getContent().getContents(). PHP_EOL;
} catch (TosClientException $ex) {
    echo $ex->getMessage() . PHP_EOL;
} catch (TosServerException $ex) {
    echo $ex->getRequestId() . PHP_EOL;
    echo $ex->getStatusCode() . PHP_EOL;
    echo $ex->getErrorCode() . PHP_EOL;
} finally {
    if ($output) {
        $output->getContent()->close();
    }
}

列举对象 #

当完成一系列上传对象操作后，可能需要查看桶中包含哪些对象。以下代码展示如何列举指定桶中的对象。

<?php

// 假设使用 composer 安装
require_once __DIR__ . '/vendor/autoload.php';

use Tos\TosClient;
use Tos\Exception\TosClientException;
use Tos\Exception\TosServerException;
use Tos\Model\ListObjectsInput;

$output = null;
try {
    $client = new TosClient([
        'region' => 'your region',
        'endpoint' => 'your endpoint',
        // 从环境变量中获取访问密钥
        'ak' => getenv('TOS_ACCESS_KEY'),
        'sk' => getenv('TOS_SECRET_KEY'),
    ]);
       
    $input = new ListObjectsInput('bucket-test');
    $output = $client->listObjects($input);

    echo $output->getRequestId() . PHP_EOL;
    // 获取对象列表
    foreach ($output->getContents() as $content) {
        echo $content->getKey() . PHP_EOL;
        echo $content->getETag() . PHP_EOL;
    }
} catch (TosClientException $ex) {
    echo $ex->getMessage() . PHP_EOL;
} catch (TosServerException $ex) {
    echo $ex->getRequestId() . PHP_EOL;
    echo $ex->getStatusCode() . PHP_EOL;
    echo $ex->getErrorCode() . PHP_EOL;
} finally {
    if ($output) {
        $output->getContent()->close();
    }
}

删除对象 #

以下代码展示如何删除指定对象。

<?php

// 假设使用 composer 安装
require_once __DIR__ . '/vendor/autoload.php';

use Tos\TosClient;
use Tos\Exception\TosClientException;
use Tos\Exception\TosServerException;
use Tos\Model\DeleteObjectInput;

$output = null;
try {
    $client = new TosClient([
        'region' => 'your region',
        'endpoint' => 'your endpoint',
        // 从环境变量中获取访问密钥
        'ak' => getenv('TOS_ACCESS_KEY'),
        'sk' => getenv('TOS_SECRET_KEY'),
    ]);
       
    $input = new DeleteObjectInput('bucket-test',  'key-test');
    $output = $client->deleteObject($input);

    echo $output->getRequestId() . PHP_EOL;
} catch (TosClientException $ex) {
    echo $ex->getMessage() . PHP_EOL;
} catch (TosServerException $ex) {
    echo $ex->getRequestId() . PHP_EOL;
    echo $ex->getStatusCode() . PHP_EOL;
    echo $ex->getErrorCode() . PHP_EOL;
}