AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 对象存储 开发参考 SDK参考 OSS PHP SDK V2（预览版） 快速入门

PHP SDK V2快速入门

更新时间：
产品详情
我的收藏

本文为您提供使用OSS PHP SDK V2进行常见存储操作的快速入门。您将学习如何安装SDK、配置访问凭证，以及执行基本操作，包括创建存储空间（Bucket）、上传、下载、列举和删除文件（Object）等。

注意事项

  • 关于OSS支持的Region与Endpoint的对应关系，请参见OSS地域和访问域名。

  • 本文以从环境变量读取访问凭证为例。更多配置访问凭证的示例，请参见配置访问凭证。

  • 使用PHP SDK发起OSS请求，您需要初始化一个OSSClient。本文通过默认配置示例来创建一个OSSClient。更多配置客户端的示例，请参见配置客户端。

前提条件

配置凭证

  1. 创建有OSS管理权限的RAM用户AccessKey。

    使用ROS脚本快速创建有OSS管理权限的RAM用户AccessKey

    在资源编排ROS控制台的创建资源栈页面的安全确认下，勾选确认，然后单击创建。

    1.png

    创建完成后，在输出中，复制创建的AccessKey。

    image

  2. 使用RAM用户AccessKey配置环境变量。

    Linux

    1. 在命令行界面执行以下命令来将环境变量设置追加到~/.bashrc 文件中。

      echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

      1. 执行以下命令使变更生效。

        source ~/.bashrc

      2. 执行以下命令检查环境变量是否生效。

        echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

    macOS

    1. 在终端中执行以下命令，查看默认Shell类型。

      echo $SHELL

      1. 根据默认Shell类型进行操作。

        Zsh

        1. 执行以下命令来将环境变量设置追加到 ~/.zshrc 文件中。

          echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

        2. 执行以下命令使变更生效。

          source ~/.zshrc

        3. 执行以下命令检查环境变量是否生效。

          echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

        Bash

        1. 执行以下命令来将环境变量设置追加到 ~/.bash_profile 文件中。

          echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile

        2. 执行以下命令使变更生效。

          source ~/.bash_profile

        3. 执行以下命令检查环境变量是否生效。

          echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

    Windows

    CMD

    1. 在CMD中运行以下命令。

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

      1. 运行以下命令，检查环境变量是否生效。

        echo %OSS_ACCESS_KEY_ID%
echo %OSS_ACCESS_KEY_SECRET%

    PowerShell

    1. 在PowerShell中运行以下命令。

      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
[Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

      1. 运行以下命令，检查环境变量是否生效。

        [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
[Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

  3. 参考上述方式修改系统环境变量后，请重启或刷新您的编译运行环境，包括IDE、命令行界面、其他桌面应用程序及后台服务，以确保最新的系统环境变量成功加载。

安装OSS PHP SDK

  • 在安装使用OSS PHP SDK前，请您参考PHP官网下载安装PHP 7.4及以上版本的运行环境。同时，请您参考composer官网下载包管理工具composer。

  • 使用包管理工具composer执行以下命令获取OSS PHP SDK V2。

  • 说明

    请根据需求选择合适的OSS PHP SDK V2版本，推荐您使用最新的版本，确保本文中的代码示例可以正常运行。关于版本功能的更多信息，请参见Releases。

    mkdir oss-php-example && cd oss-php-example && composer require alibabacloud/oss-v2

  • 在您的项目中使用以下代码引入OSS PHP SDK的包。

    require_once __DIR__ . '/../vendor/autoload.php';

快速使用

以下示例程序演示了如何创建存储空间（Bucket）、上传、下载、列举和删除文件（Object）等。

创建存储空间

<?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名称（必填）
];

// 将参数描述转换为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名称

// 加载环境变量中的凭证信息
// 使用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);

// 创建PutBucketRequest对象，用于创建Bucket
$request = new Oss\Models\PutBucketRequest(bucket: $bucket);

// 执行创建Bucket操作
$result = $client->putBucket($request);

// 打印创建结果
// 输出HTTP状态码和请求ID，用于验证创建是否成功
printf(
    'status code:' . $result->statusCode . PHP_EOL . // HTTP状态码，例如200表示成功
    'request id:' . $result->requestId . PHP_EOL     // 请求ID，用于调试或追踪请求
);

上传文件

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

// 创建GetObjectRequest对象，用于获取指定对象的内容
$request = new Oss\Models\GetObjectRequest(bucket: $bucket, key: $key);

// 执行获取对象操作
$result = $client->getObject($request);

// 打印获取结果
// 输出HTTP状态码、请求ID以及对象的内容
printf(
    'status code:' . $result->statusCode . PHP_EOL . // HTTP状态码，例如200表示成功
    'request id:' . $result->requestId . PHP_EOL .   // 请求ID，用于调试或追踪请求
    'body:' . $result->body->getContents()           // 对象的内容，使用getContents()方法读取流数据
);

列举文件

<?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名称（必填）
];

// 将参数描述转换为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名称

// 加载环境变量中的凭证信息
// 使用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);

// 创建Paginator对象，用于分页列出Bucket中的对象
// ListObjectsV2Paginator支持高效地分页遍历对象列表
$paginator = new Oss\Paginator\ListObjectsV2Paginator(client: $client);
$iter = $paginator->iterPage(new Oss\Models\ListObjectsV2Request(bucket: $bucket)); // 初始化分页迭代器

// 遍历对象分页结果
foreach ($iter as $page) {
    foreach ($page->contents ?? [] as $object) {
        // 打印每个对象的关键信息
        // 输出对象的Key、类型和大小
        print("Object: $object->key, $object->type, $object->size\n");
    }
}

删除文件

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

// 创建DeleteObjectRequest对象，用于删除指定的对象
$request = new Oss\Models\DeleteObjectRequest(bucket: $bucket, key: $key);

// 执行删除对象操作
$result = $client->deleteObject($request);

// 打印删除结果
// 输出HTTP状态码和请求ID，用于验证删除是否成功
printf(
    'status code:' . $result->statusCode . PHP_EOL . // HTTP状态码，例如204表示删除成功
    'request id:' . $result->requestId . PHP_EOL     // 请求ID，用于调试或追踪请求
);

运行示例

  1. 以上传文件为例，在您的测试工程目录下创建put_object.php文件，将上传文件代码拷贝至put_object.php文件中。

  2. 请替换以下命令里的"yourRegion"、"yourBucketName"、"yourObjectName"为您的实际配置，其中yourRegion填写bucket所在地域，例如华东1（杭州）填写为cn-hangzhou。

    php put_object.php --region "yourRegion" --bucket "yourBucketName" --key "yourObjectName"

常见问题

当使用SDK时遇到报错AccessDenied该如何进行排查？

当您遇到AccessDenied错误时通常是因为没有相应的访问权限。以下是解决此问题的步骤：

  1. 确认AccessKey ID和AccessKey Secret：请确保您使用了正确的AccessKey ID和AccessKey Secret。详情请参见创建AccessKey。

  2. 检查RAM用户权限：确认RAM用户是否拥有Bucket或Object相关操作权限。具体步骤，请参见为RAM用户授权。

  3. 检查Bucket Policy：如果错误信息中提到“Access denied by bucket policy”，则表明是受到Bucket Policy的策略拒绝了。详情请参考Bucket Policy。

  4. 更多错误类型的查询，请您参阅EC错误码，例如关于访问控制方面的常见报错，可参见03-ACCESS_CONTROL。

相关文档

  • 关于OSS PHP SDK V2的更多信息，请参见官方文档。

  • 关于OSS PHP SDK V2更多功能的代码示例，请参见Github示例。

上一篇：OSS PHP SDK V2（预览版）下一篇：错误自助排查