通过PHP初始化与OSS服务建立连接_对象存储(OSS)-阿里云帮助中心

OssClient是OSS的PHP客户端，用于管理存储空间和文件等OSS资源。使用PHP SDK发起OSS请求时，您需要初始化一个OssClient实例，并根据需要修改默认配置项。

新建OssClient

V4签名（推荐）

推荐使用更安全的V4签名算法。使用V4签名初始化时，除指定Endpoint以外，您还需要指定阿里云通用Region ID作为发起请求地域的标识，示例值为cn-hangzhou。同时声明OssClient::OSS_SIGNATURE_VERSION_V4。OSS PHP SDK 2.7.0及以上版本支持V4签名。

以使用OSS域名新建OssClient时使用V4签名为例，其他通过自定义域名、STS等新建OssClient的场景可参考以下示例执行相应修改。

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;
use OSS\Core\OssException;

try {
    // 从环境变量中获取访问凭证,并保存在provider中。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
    $provider = new EnvironmentVariableCredentialsProvider();
    // 填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
    $endpoint = "https://oss-cn-hangzhou.aliyuncs.com";    
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,        
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        // 填写Endpoint对应的Region信息，例如cn-hangzhou。
        "region" => "cn-hangzhou"
    );
    $ossClient = new OssClient($config);
} catch (OssException $e) {
    printf($e->getMessage() . "\n");
    return;
}

V1签名（不推荐）

重要

阿里云对象存储OSS自2025年03月01日起不再对新用户（即新UID ）开放使用V1签名，并将于2025年09月01日起停止更新与维护且不再对新增Bucket开放使用V1签名。请尽快切换到V4签名，避免影响服务。更多信息，请参见公告说明。

使用OSS域名新建OssClient

以下代码使用OSS域名新建OssClient。关于不同地域的OSS域名，请参见OSS地域和访问域名。

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;
use OSS\CoreOssException;

// 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。 
$provider = new EnvironmentVariableCredentialsProvider();
// Endpoint以杭州为例，其它Region请按实际情况填写。
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";

try {
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint
    );
    $ossClient = new OssClient($config);
} catch (OssException $e) {
    print $e->getMessage();
}

使用自定义域名新建OssClient

以下代码使用自定义域名新建OssClient。关于使用自定义域名访问OSS的更多信息，请参见绑定自定义域名至Bucket默认域名。

重要

使用自定义域名时，无法使用listBuckets方法。

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;
use OSS\CoreOssException;

// 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。 
$provider = new EnvironmentVariableCredentialsProvider();
// 填写自定义域名，例如http://example.com。
$endpoint = "http://example.com";

try {
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "cname"	=> true
    );
    $ossClient = new OssClient($config);    
} catch (OssException $e) {
    print $e->getMessage();
}

使用STS新建OssClient

以下代码用于使用STS新建一个OssClient。

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;
use OSS\Core\OssException;
// 运行本代码示例之前，请确保已在环境变量中配置STS的访问密钥（AccessKey ID和AccessKey Secret）和安全令牌（SecurityToken）。
$provider = new EnvironmentVariableCredentialsProvider();
// Endpoint以杭州为例，其它Region请按实际情况填写。
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";

try {
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,        
    );
    $ossClient = new OssClient($config);
} catch (OssException $e) {
    print $e->getMessage();
}

使用EcsRamRole新建OssClient

在云服务器ECS上，您可以通过实例RAM角色的方式访问OSS。实例RAM角色允许您将一个角色关联到云服务器实例，在实例内部基于临时凭证STS访问OSS。临时凭证由系统自动生成和更新，应用程序可以使用指定的实例元数据URL获取临时凭证。

重要

使用EcsRamRole新建OssClient之前，您需要执行以下命令通过composer的方式安装SDK。

composer require alibabacloud/credentials

以下代码用于使用EcsRamRole新建OssClient。

<?php

if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
  }
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
  require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\Credentials\CredentialsProvider;
use AlibabaCloud\Credentials\Credential;
use OSS\Credentials\StaticCredentialsProvider;
use OSS\Core\OssException;
use OSS\OssClient;
class AlibabaCloudCredentialsWrapper implements CredentialsProvider{
    /**
     * @var \OSS\Credentials\Credentials
     */
    private $wrapper;
    public function __construct($wrapper){
        $this->wrapper = $wrapper;
    }
    public function getCredentials(){
        $ak = $this->wrapper->getAccessKeyId();
        $sk = $this->wrapper->getAccessKeySecret();
        $token = $this->wrapper->getSecurityToken();
        return new StaticCredentialsProvider($ak, $sk, $token);
    }
}
$ecsRamRole = new Credential(array(
    // 填写Credential类型，固定值为ecs_ram_role。
    'type'      => 'ecs_ram_role',
    // 填写角色名称。
    'role_name' => 'EcsRamRoleOssTest',
));
$providerWarpper = new AlibabaCloudCredentialsWrapper($ecsRamRole);
$provider = $providerWarpper->getCredentials();
$config = array(
    'provider' => $provider,
    // 以华东1（杭州）为例，填写为https://oss-cn-hangzhou.aliyuncs.com。其他Region请按实际情况填写。
    'endpoint'=> 'https://oss-cn-hangzhou.aliyuncs.com'
);
try {
    $ossClient = new OssClient($config);
} catch (OssException $e) {
    print $e->getMessage();
}

使用STSAssumeRole新建OssClient

重要

使用STSAssumeRole新建OssClient之前，您需要执行以下命令通过composer的方式安装SDK。

composer require alibabacloud/credentials

以下代码用于使用STSAssumeRole新建OssClient。

<?php

if (is_file(__DIR__ . '/../autoload.php')) {
 require_once __DIR__ . '/../autoload.php';
 }
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
 require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\Credentials\CredentialsProvider;
use AlibabaCloud\Credentials\Credential;
use OSS\Credentials\StaticCredentialsProvider;
use OSS\Core\OssException;
use OSS\OssClient;
class AlibabaCloudCredentialsWrapper implements CredentialsProvider{
 /**
 * @var \OSS\Credentials\Credentials
 */
 private $wrapper;
 public function __construct($wrapper){
 $this->wrapper = $wrapper;
 }
 public function getCredentials(){
 $ak = $this->wrapper->getAccessKeyId();
 $sk = $this->wrapper->getAccessKeySecret();
 $token = $this->wrapper->getSecurityToken();
 return new StaticCredentialsProvider($ak, $sk, $token);
 }
}
$ramRoleArn = new Credential(array(
 // 填写Credential类型，固定值为ram_role_arn。
 'type' => 'ram_role_arn',
 // 运行本代码示例之前，请确保已使用RAM用户的访问密钥设置环境变量YOUR_ACCESS_KEY_ID和YOUR_ACCESS_KEY_SECRET。
 'access_key_id' => getenv('YOUR_ACCESS_KEY_ID'),
 'access_key_secret' => getenv('YOUR_ACCESS_KEY_SECRET'),
 // 填写角色的ARN信息，即需要扮演的角色ID。格式为acs:ram::$accountID:role/$roleName。
 'role_arn' => 'acs:ram::17464958********:role/ossststest',
 // 自定义角色会话名称，用于区分不同的令牌。
 'role_session_name' => 'yourRoleSessionName',
 // 自定义权限策略。
 'policy' => '',
));
$providerWarpper = new AlibabaCloudCredentialsWrapper($ramRoleArn);
$provider = $providerWarpper->getCredentials();
$config = array(
 'provider' => $provider,
 // 以华东1（杭州）为例，填写为https://oss-cn-hangzhou.aliyuncs.com。其他Region请按实际情况填写。
 'endpoint'=> 'https://oss-cn-hangzhou.aliyuncs.com'
);
try {
 $ossClient = new OssClient($config);
 var_dump($ossClient);
} catch (OssException $e) {
 print $e->getMessage();
}

配置OssClient

您可以通过OssClient配置代理、连接超时、最大连接数等参数。

参数	描述	方法
timeout	设置Socket层传输数据的超时时间，默认值为5184000，单位为秒。	$ossClient->setTimeout(60);
connectTimeout	设置建立连接的超时时间，默认值为10，单位为秒。	$ossClient->setConnectTimeout(600);
maxRetries	请求失败后最大的重试次数。默认3次。	$ossClient->setMaxTries(5);
useSSL	是否开启SSL证书校验。取值如下： true：开启SSL证书校验。 false（默认值）：关闭SSL证书校验。	$ossClient->setUseSSL(true);

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;
use OSS\CoreOssException;
// 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。 
$provider = new EnvironmentVariableCredentialsProvider();
// Endpoint以杭州为例，其它Region请按实际情况填写。
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";

try {
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);
    // 设置建立连接的超时时间。
    $ossClient->setConnectTimeout(300);
    // 设置失败请求重试次数。
    $ossClient->setMaxTries(5);    
    // 设置Socket层传输数据的超时时间。
    $ossClient->setTimeout(30);
    // 设置是否开启SSL证书校验。
    $ossClient->setUseSSL(true);
} catch (OssException $e) {
    print $e->getMessage();
}

配置代理服务器

PHP 5.3及以上版本支持配置代理服务器。

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;
use OSS\Core\OssException;
// 运行本代码示例之前，请确保已在环境变量中配置STS的访问密钥（AccessKey ID和AccessKey Secret）和安全令牌（SecurityToken）。
$provider = new EnvironmentVariableCredentialsProvider();
// Endpoint以杭州为例，其它Region请按实际情况填写。
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 设置代理服务器地址，例如http://<用户名>:<密码>@<代理ip>:<代理端口>。
$request_proxy = "yourRequestProxy"
try {
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "request_proxy"=> $request_proxy,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);    
} catch (OssException $e) {
    print $e->getMessage();
}