Initialize an OSS client with the PHP SDK V1 - Object Storage Service

OssClient is the PHP client for Object Storage Service (OSS). You can use it to manage OSS resources, such as buckets and files. To send an OSS request using the PHP software development kit (SDK), you must initialize an OssClient instance and modify its default configurations as needed.

Create an OssClient

Signature V4 (Recommended)

Use the more secure Signature V4 algorithm. When you initialize a client with Signature V4, you must specify an endpoint and an Alibaba Cloud general-purpose region ID. The region ID identifies the region where the request originates. For example, specify cn-hangzhou. You must also declare OssClient::OSS_SIGNATURE_VERSION_V4. OSS PHP SDK versions 2.7.0 and later support Signature V4.

The following code provides an example of how to create an OssClient using an OSS domain name and Signature V4. For other scenarios, such as creating an OssClient using a custom domain name or Security Token Service (STS), you can modify the code in this example.

<?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 {
    // Obtain access credentials from environment variables and save them to the provider. Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
    $provider = new EnvironmentVariableCredentialsProvider();
    // Specify the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to 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,
        // Specify the region that corresponds to the endpoint. For example, specify cn-hangzhou.
        "region" => "cn-hangzhou"
    );
    $ossClient = new OssClient($config);
} catch (OssException $e) {
    printf($e->getMessage() . "\n");
    return;
}

Signature V1 (Not recommended)

Important

From March 1, 2025, the V1 signature algorithm of OSS is no longer available to new customers with new UIDs. From September 1, 2025, OSS no longer updates and maintains the V1 signature algorithm, and the V1 signature algorithm is no longer available for new buckets. Upgrade V1 signatures to V4 signatures at the earliest opportunity to prevent impact on your business.

Create an OssClient using an OSS domain name

The following code provides an example of how to create an OssClient using an OSS domain name. For more information about the OSS domain names of different regions, see Regions and endpoints.

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

// Obtain access credentials from environment variables. Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set. 
$provider = new EnvironmentVariableCredentialsProvider();
// The endpoint of the China (Hangzhou) region is used as an example. Specify an endpoint based on your actual 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();
}

Create an OssClient using a custom domain name

The following code provides an example of how to create an OssClient using a custom domain name. For more information about how to access OSS using a custom domain name, see Access OSS using a custom domain name.

Important

You cannot use the listBuckets method with a custom domain name.

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

// Obtain access credentials from environment variables. Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set. 
$provider = new EnvironmentVariableCredentialsProvider();
// Specify a custom domain name. For example, 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();
}

Create an OssClient using STS

The following code provides an example of how to create an OssClient using STS.

<?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;
// Before you run this sample code, make sure that the AccessKey pair (AccessKey ID and AccessKey secret) and security token of STS are configured in the environment variables.
$provider = new EnvironmentVariableCredentialsProvider();
// The endpoint of the China (Hangzhou) region is used as an example. Specify an endpoint based on your actual 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();
}

Create an OssClient using an instance RAM role

You can access OSS from an Elastic Compute Service (ECS) instance using an instance RAM role. An instance RAM role lets you associate a role with an ECS instance. This lets you access OSS from within the instance using temporary credentials from STS. The system automatically generates and updates the temporary credentials. Your application can retrieve the temporary credentials from a specified instance metadata URL.

Important

Before you create an OssClient using an instance RAM role, you must run the following command to install the SDK with Composer.

composer require alibabacloud/credentials

The following code provides an example of how to create an OssClient using an instance RAM role.

<?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(
    // Specify the credential type. The value is fixed to ecs_ram_role.
    'type'      => 'ecs_ram_role',
    // Specify the role name.
    'role_name' => 'EcsRamRoleOssTest',
));
$providerWarpper = new AlibabaCloudCredentialsWrapper($ecsRamRole);
$provider = $providerWarpper->getCredentials();
$config = array(
    'provider' => $provider,
    // The endpoint of the China (Hangzhou) region is used as an example. Set it to https://oss-cn-hangzhou.aliyuncs.com. For other regions, specify the actual endpoint.
    'endpoint'=> 'https://oss-cn-hangzhou.aliyuncs.com'
);
try {
    $ossClient = new OssClient($config);
} catch (OssException $e) {
    print $e->getMessage();
}

Create an OssClient using STSAssumeRole

Important

Before you create an OssClient using STSAssumeRole, you must run the following command to install the SDK with Composer.

composer require alibabacloud/credentials

The following code provides an example of how to create an OssClient using STSAssumeRole.

<?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(
 // Specify the credential type. The value is fixed to ram_role_arn.
 'type' => 'ram_role_arn',
 // Before you run this sample code, make sure that you have used the AccessKey pair of a RAM user to set the YOUR_ACCESS_KEY_ID and YOUR_ACCESS_KEY_SECRET environment variables.
 'access_key_id' => getenv('YOUR_ACCESS_KEY_ID'),
 'access_key_secret' => getenv('YOUR_ACCESS_KEY_SECRET'),
 // Specify the Alibaba Cloud Resource Name (ARN) of the role to assume. The format is acs:ram::$accountID:role/$roleName.
 'role_arn' => 'acs:ram::17464958********:role/ossststest',
 // Specify a custom role session name to distinguish different tokens.
 'role_session_name' => 'yourRoleSessionName',
 // Specify a custom policy.
 'policy' => '',
));
$providerWarpper = new AlibabaCloudCredentialsWrapper($ramRoleArn);
$provider = $providerWarpper->getCredentials();
$config = array(
 'provider' => $provider,
 // The endpoint of the China (Hangzhou) region is used as an example. Set it to https://oss-cn-hangzhou.aliyuncs.com. For other regions, specify the actual endpoint.
 'endpoint'=> 'https://oss-cn-hangzhou.aliyuncs.com'
);
try {
 $ossClient = new OssClient($config);
 var_dump($ossClient);
} catch (OssException $e) {
 print $e->getMessage();
}

Configure an OssClient

You can configure parameters for an OssClient, such as the proxy server, connection timeout, and maximum connections.

Parameter	Description	Method
timeout	The timeout period for data transmission at the socket layer. The default value is 5184000. Unit: seconds.	$ossClient->setTimeout(60);
connectTimeout	The timeout period for establishing a connection. The default value is 10. Unit: seconds.	$ossClient->setConnectTimeout(600);
maxRetries	The maximum number of retries for a failed request. The default value is 3.	$ossClient->setMaxTries(5);
useSSL	Specifies whether to enable SSL certificate verification. Valid values: true: enables SSL certificate verification. false (default): disables SSL certificate verification.	$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;
// Obtain access credentials from environment variables. Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set. 
$provider = new EnvironmentVariableCredentialsProvider();
// The endpoint of the China (Hangzhou) region is used as an example. Specify an endpoint based on your actual 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);
    // Set the connection timeout period.
    $ossClient->setConnectTimeout(300);
    // Set the maximum number of retries for failed requests.
    $ossClient->setMaxTries(5);    
    // Set the timeout period for data transmission at the socket layer.
    $ossClient->setTimeout(30);
    // Specify whether to enable SSL certificate verification.
    $ossClient->setUseSSL(true);
} catch (OssException $e) {
    print $e->getMessage();
}

Configure a proxy server

PHP versions 5.3 and later support proxy server configuration.

<?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;
// Before you run this sample code, make sure that the AccessKey pair (AccessKey ID and AccessKey secret) and security token of STS are configured in the environment variables.
$provider = new EnvironmentVariableCredentialsProvider();
// The endpoint of the China (Hangzhou) region is used as an example. Specify an endpoint based on your actual region.
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// Set the proxy server address. For example, http://<username>:<password>@<proxy_ip>:<proxy_port>.
$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();
}