PHP配置客户端

注意事项

• 初始化OSS Client前，您需要配置访问凭证，本文以从环境变量读取访问凭证为例，更多配置示例请参见配置访问凭证。

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

前置条件

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

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

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

   

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

   

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、命令行界面、其他桌面应用程序及后台服务，以确保最新的系统环境变量成功加载。

默认配置示例

<?php

// 引入自动加载文件，确保依赖库能够正确加载
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// 使用EnvironmentVariableCredentialsProvider从环境变量中读取Access Key ID和Access Key Secret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# 加载SDK的默认配置，并设置凭证提供者
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider); // 设置凭证提供者

// 方式一： 只填写Region即可
// 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
$cfg->setRegion(region: "cn-hangzhou");

// // 方式二： 直接填写Region和Endpoint
// // 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
// // 填写Bucket所在地域对应的公网Endpoint。以华东1（杭州）为例，Endpoint填写为'https://oss-cn-hangzhou.aliyuncs.com',
// // 如需指定为http协议，请在指定域名时填写为'http://oss-cn-hangzhou.aliyuncs.com'
// $cfg->setRegion(region: 'cn-hangzhou')->setEndpoint(endpoint: 'https://oss-cn-hangzhou.aliyuncs.com');

// 创建OSS客户端实例
$client = new Oss\Client($cfg);

// 使用创建好的client执行后续操作...

常见场景配置示例

内网域名配置示例

当您的应用部署在阿里云的ECS实例上，并且需要频繁访问同地域的OSS资源时，使用内网域名可以降低流量成本并提高访问速度。

以下是使用OSS内网域名配置OSSClient的示例代码。

<?php

// 引入自动加载文件，确保依赖库能够正确加载
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// 使用EnvironmentVariableCredentialsProvider从环境变量中读取Access Key ID和Access Key Secret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# 加载SDK的默认配置，并设置凭证提供者
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider); // 设置凭证提供者

// 方式一： 填写Region并设置setUseInternalEndpoint为true
// 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
$cfg->setRegion('cn-hangzhou')->setUseInternalEndpoint(true);

// // 方式二： 直接填写Region和Endpoint
// // 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
// // 填写Bucket所在地域对应的内网Endpoint。以华东1（杭州）为例，Endpoint填写为'https://oss-cn-hangzhou-internal.aliyuncs.com',
// // 如需指定为http协议，请在指定域名时填写为'http://oss-cn-hangzhou-internal.aliyuncs.com'
// $cfg->setRegion('cn-hangzhou')->setEndpoint('https://oss-cn-hanghzou-internal.aliyuncs.com');

// 创建OSS客户端实例
$client = new Oss\Client($cfg);

// 使用创建好的client执行后续操作...

自定义域名配置示例

当您有多个不同的OSS Bucket用于不同的目的时，可以通过为每个Bucket设置不同的子域名来更好地管理和组织资源。

以下是使用自定义域名配置OSSClient的示例代码，以 'www.example-***.com' 域名 绑定到 'cn-hangzhou' 区域的存储空间为例

<?php

// 引入自动加载文件，确保依赖库能够正确加载
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// 使用EnvironmentVariableCredentialsProvider从环境变量中读取Access Key ID和Access Key Secret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# 加载SDK的默认配置，并设置凭证提供者
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider); // 设置凭证提供者

// 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
// 填写您的自定义域名。例如www.example-***.com，请注意，setUseCname设置true开启CNAME选项，否则无法使用自定义域名
$cfg->setRegion('cn-hangzhou')->setEndpoint('www.example-***.com')->setUseCname(true);

// 创建OSS客户端实例
$client = new Oss\Client($cfg);

// 使用创建好的client执行后续操作...

传输加速域名配置示例

以下是使用传输加速域名配置OSSClient的示例代码。

<?php

// 引入自动加载文件，确保依赖库能够正确加载
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// 使用EnvironmentVariableCredentialsProvider从环境变量中读取Access Key ID和Access Key Secret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# 加载SDK的默认配置，并设置凭证提供者
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider); // 设置凭证提供者

// 方式一： 填写Region并设置setUseAccelerateEndpoint为true
// 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
$cfg->setRegion('cn-hangzhou')->setUseAccelerateEndpoint(true);

// // 方式二： 直接填写Region和Endpoint
// // 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
// // 填写Bucket所在地域对应的传输加速Endpoint。以华东1（杭州）为例，Endpoint填写为'https://oss-accelerate.aliyuncs.com',
// $cfg->setRegion('cn-hangzhou')->setEndpoint('https://oss-accelerate.aliyuncs.com');

// 创建OSS客户端实例
$client = new Oss\Client($cfg);

// 使用创建好的client执行后续操作...

专有域配置示例

以下是使用专有域配置OSSClient的示例代码。

<?php

// 引入自动加载文件，确保依赖库能够正确加载
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// 使用EnvironmentVariableCredentialsProvider从环境变量中读取Access Key ID和Access Key Secret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# 加载SDK的默认配置，并设置凭证提供者
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider); // 设置凭证提供者

// 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
// 填写您的专有域。例如：https://service.corp.example.com
$cfg->setRegion('cn-hangzhou')->setEndpoint('https://service.corp.example.com');

// 创建OSS客户端实例
$client = new Oss\Client($cfg);

// 使用创建好的client执行后续操作...

连接超时配置示例

以下代码用于设置OSSClient的连接超时时间。

<?php

// 引入自动加载文件，确保依赖库能够正确加载
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// 使用EnvironmentVariableCredentialsProvider从环境变量中读取Access Key ID和Access Key Secret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# 加载SDK的默认配置，并设置凭证提供者
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider); // 设置凭证提供者

// 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou
$cfg->setRegion(region: "cn-hangzhou");

# 设置建立连接的超时时间
$cfg->setConnectTimeout(connectTimeout: 30);

# 设置应用读写数据的超时时间
$cfg->setReadwriteTimeout(readwriteTimeout:30);

// 创建OSS客户端实例
$client = new Oss\Client($cfg);

// 使用创建好的client执行后续操作...

swoole下使用协程配置示例

以下代码演示了基于swoole框架下创建支持协程的 OSS 客户端示例。

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

use AlibabaCloud\Oss\V2 as Oss;
use GuzzleHttp\HandlerStack;
use Hyperf\Guzzle\CoroutineHandler;
use function Hyperf\Coroutine\co;

// 配置 OSS 客户端
$region = 'cn-hangzhou'; // OSS 区域
$bucket = 'bucket-name'; // 目标 Bucket 名称
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider(); // 从环境变量加载凭证
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider); // 设置凭证提供者
$cfg->setRegion(region: $region); // 设置区域
$cfg->setEndpoint(endpoint: 'http://oss-cn-hangzhou.aliyuncs.com'); // 设置访问域名

// 创建支持协程的 OSS 客户端
$client = new Oss\Client(config: $cfg, options: ['handler' => HandlerStack::create(handler: new CoroutineHandler())]);

// 协程任务 1：上传 swoole.txt
co(function () use ($client, $bucket) {
    try {
        $key = 'swoole.txt'; // 对象名称
        $data = 'Hello OSS'; // 对象内容
        $request = new Oss\Models\PutObjectRequest($bucket, $key); // 创建上传请求
        $request->body = Oss\Utils::streamFor($data); // 设置请求体
        $result = $client->putObject(request: $request); // 执行上传
        echo "Task 1 Result:\n" . var_export($result, true) . "\n"; // 输出结果
    } catch (\Exception $e) {
        echo "Task 1 Error: " . $e->getMessage() . "\n"; // 捕获异常
    }
});

// 协程任务 2：上传 hyperf.txt
co(function () use ($client, $bucket) {
    try {
        $key = 'hyperf.txt'; // 对象名称
        $data = 'Hello OSS'; // 对象内容
        $request = new Oss\Models\PutObjectRequest($bucket, $key); // 创建上传请求
        $request->body = Oss\Utils::streamFor($data); // 设置请求体
        $result = $client->putObject($request); // 执行上传
        echo "Task 2 Result:\n" . var_export($result, true) . "\n"; // 输出结果
    } catch (\Exception $e) {
        echo "Task 2 Error: " . $e->getMessage() . "\n"; // 捕获异常
    }
});

配置参数汇总

常见问题

相关文档

关于配置客户端的更多内容，请参见开发者指南。