All Products
Search
Document Center

Object Storage Service:Initialize an OSSClient instance by using OSS SDK for PHP

Last Updated:Mar 12, 2024

OSSClient is the PHP client of Object Storage Service (OSS). It is used to manage OSS resources, such as buckets and objects. To use OSS SDK for PHP to initiate a request, you must initialize an OSSClient instance and modify the default configuration items.

Create an OSSClient instance

Use the V1 signature algorithm

Create an OSSClient instance by using an OSS endpoint

The following sample code provides an example on how to create an OSSClient instance by using an OSS endpoint. For more information about the OSS endpoints 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 the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.  
$provider = new EnvironmentVariableCredentialsProvider();
// In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. 
$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 instance by using a custom domain name

The following sample code provides an example on how to create an OSSClient instance by using a custom domain name. For more information, see Map a custom domain name to the default domain name of a bucket.

Important

The listBuckets method is unavailable when a custom domain name is used.

<?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 the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.  
$provider = new EnvironmentVariableCredentialsProvider();
// Specify the custom domain name. 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 instance by using access credentials obtained from STS

The following sample code provides an example on how to create an OSSClient instance by using access credentials obtained from Security Token Service (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 the sample code, make sure that the access credentials are configured. The access credentials consist of an AccessKey pair and a security token. The AccessKey pair consists of an AccessKey ID and an AccessKey secret. 
$provider = new EnvironmentVariableCredentialsProvider();
// In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. 
$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 instance by using EcsRamRole

You can attach a RAM role to an Elastic Compute Service (ECS) instance to access OSS from the instance by using temporary access credentials that are obtained from STS. STS temporary access credentials are automatically generated and updated. Applications can obtain the STS temporary access credentials by using the instance metadata URL.

Important

Before you use EcsRamRole to create an OSSClient instance, run the following command to install OSS SDK for PHP by using Composer:

composer require alibabacloud/credentials

The following sample code provides an example on how to create an OSSClient instance by using EcsRamRole:

<?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(
    // Set the type of the credential 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,
    // Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. Specify your actual endpoint. 
    'endpoint'=> 'https://oss-cn-hangzhou.aliyuncs.com'
);
try {
    $ossClient = new OssClient($config);
} catch (OssException $e) {
    print $e->getMessage();
}

Create an OSSClient instance by using STSAssumeRole

Important

Before you use STSAssumeRole to create an OSSClient instance, run the following command to install OSS SDK for PHP by using Composer:

composer require alibabacloud/credentials

The following sample code provides an example on how to create an OSSClient instance by 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(
 // Set the type of the credential to ram_role_arn. 
 'type' => 'ram_role_arn',
 // Before you run the sample code, make sure that the YOUR_ACCESS_KEY_ID and YOUR_ACCESS_KEY_SECRET environment variables are configured by using the AccessKey pair of the RAM user. 
 '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 RAM role, which is the ID of the role to be assumed. Format: acs:ram::$accountID:role/$roleName. 
 'role_arn' => 'acs:ram::17464958********:role/ossststest',
 // Specify a custom session name for the role to distinguish different tokens. 
 'role_session_name' => 'yourRoleSessionName',
 // Specify a custom policy. 
 'policy' => '',
));
$providerWarpper = new AlibabaCloudCredentialsWrapper($ramRoleArn);
$provider = $providerWarpper->getCredentials();
$config = array(
 'provider' => $provider,
 // Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. Specify your actual endpoint. 
 'endpoint'=> 'https://oss-cn-hangzhou.aliyuncs.com'
);
try {
 $ossClient = new OssClient($config);
 var_dump($ossClient);
} catch (OssException $e) {
 print $e->getMessage();
}

Use the V4 signature algorithm (recommended)

If you want to use the V4 signature algorithm, you must add the region of the endpoint to the OSSClient instance and set OssClient to OSS_SIGNATURE_VERSION_V4 before initialization. The V4 signature algorithm is more secure than the V1 signature algorithm. OSS SDK for PHP 2.7.0 and later support V4 signatures.

The following sample code provides an example on how to create an OSSClient instance by using an OSS endpoint and sign the request by using the V4 signature algorithm. To create an OSSClient instance by using a custom domain name or access credentials obtained from STS, you can refer to the following sample code and change the variables:

<?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 the credentials in the provider. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
    $provider = new EnvironmentVariableCredentialsProvider();
    // Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located 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 of the endpoint. Example: cn-hangzhou. 
        "region" => "cn-hangzhou"
    );
    $ossClient = new OssClient($config);
} catch (OssException $e) {
    printf($e->getMessage() . "\n");
    return;
}

Configure an OSSClient instance

You can use an OSSClient instance to configure parameters, such as the proxy, connection timeout, and maximum number of connections.

Parameter

Description

Method

timeout

The timeout period for data transmission at the Socket layer. Unit: seconds. Default value: 5184000.

$ossClient->setTimeout(60);

connectTimeout

The timeout period to establish a connection. Unit: seconds. Default value: 10.

$ossClient->setConnectTimeout(600);

maxRetries

The maximum number of retries when a request error occurs. Default value: 3.

$ossClient->setMaxTries(5);

useSSL

Specifies whether to enable SSL-based authentication. Valid values:

  • true

  • false

$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 the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.  
$provider = new EnvironmentVariableCredentialsProvider();
// In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. 
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";

try {
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
    );
    $ossClient = new OssClient($config);
    // Specify a timeout period for establishing a connection. 
    $ossClient->setConnectTimeout(300);
    // Specify the maximum number of retries when a request error occurs. 
    $ossClient->setMaxTries(5);    
    // Specify the timeout period for data transmission at the socket layer. 
    $ossClient->setTimeout(30);
    // Specify whether to enable SSL-based authentication. 
    $ossClient->setUseSSL(true);
} catch (OssException $e) {
    print $e->getMessage();
}            

Configure a proxy server

You can configure a proxy server for OSS SDK for PHP 5.3 or later.

?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 the sample code, make sure that the access credentials are configured. The access credentials consist of an AccessKey pair and a security token. The AccessKey pair consists of an AccessKey ID and an AccessKey secret. 
$provider = new EnvironmentVariableCredentialsProvider();
// In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. 
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// Specify the IP address of the proxy server. Example: http://<username>:<password>@<proxyip>:<proxyport>. 
$request_proxy = "yourRequestProxy"
try {
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "request_proxy"=> $request_proxy,
    );
    $ossClient = new OssClient($config);    
} catch (OssException $e) {
    print $e->getMessage();
}