Object Storage Service:OSS SDK for PHP 2.0

<?php

/**
 * Complete guide to OSS SDK for PHP 2.0 client configuration
 *
 * ===========================================
 * V4 signature and region configuration
 * ===========================================
 * • OSS SDK for PHP 2.0 uses the V4 signature algorithm by default.
 * • You must specify an Alibaba Cloud region ID when initializing the client.
 * • For a list of region IDs, see Regions and endpoints.
 *
 * ===========================================
 * Endpoint configuration
 * ===========================================
 * • The SDK lets you customize the service endpoint by using the endpoint parameter.
 * • If you omit the endpoint, the SDK automatically constructs a public endpoint from the region information.
 * • For example, if the region is '<region-id>', the constructed endpoint is 'https://oss-<region-id>.aliyuncs.com'.
 *
 * ===========================================
 * Protocol selection
 * ===========================================
 * • The SDK uses HTTPS by default to construct endpoints, which is the recommended protocol.
 * • To use the HTTP protocol, include http:// in the endpoint.
 * • HTTPS example: 'https://oss-<region-id>.aliyuncs.com'
 * • HTTP example: 'http://oss-<region-id>.aliyuncs.com'
 */

// Import the autoloader to correctly load dependencies.
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// EnvironmentVariableCredentialsProvider reads the AccessKey ID and AccessKey Secret from environment variables.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# Load the default SDK configurations and set the credential provider.
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider);

// Method 1: Specify only the region (recommended). The SDK automatically constructs an HTTPS endpoint.
$cfg->setRegion(region: "<region-id>");

// // Method 2: Specify both the region and the endpoint.
// $cfg->setRegion(region: '<region-id>')->setEndpoint(endpoint: 'https://oss-<region-id>.aliyuncs.com');

// Create an OSS client instance.
$client = new Oss\Client($cfg);

// The data to upload.
$data = 'Hello OSS';

// Create a PutObjectRequest object to upload an object.
$request = new Oss\Models\PutObjectRequest(
                bucket: "Your Bucket Name",
                key: "Your Object Key",
            );
$request->body = Oss\Utils::streamFor($data); // Set the request body to a data stream.

// Perform the upload operation.
$result = $client->putObject($request);

// Print the upload result.
printf(
    'status code: %s' . PHP_EOL . // The HTTP status code.
    'request id: %s' . PHP_EOL .  // The request ID.
    'etag: %s' . PHP_EOL,         // The ETag of the object.
    $result->statusCode,
    $result->requestId,
    $result->etag
);

status code: 200
request id: 687F2BEEDC44E0313527BA07
etag: "F0F18C2C66AE1DD512BDCD4366F76DA3"

<?php

// Include the autoloader file to load dependencies.
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Use EnvironmentVariableCredentialsProvider to obtain the AccessKey ID and AccessKey Secret from environment variables. $credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider(); // Load the default SDK configuration and set the credential provider. $cfg = Oss\Config::loadDefault(); $cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider); // Specify your custom domain name, such as www.example-***.com. // Note: setUseCname must be set to true to use a custom domain name. // Calling the PutCname operation requires PHP 8 or later. $cfg->setRegion('<region-id>')->setEndpoint('www.example-***.com')->setUseCname(true); // Create an OSS client instance. $client = new Oss\Client($cfg); // Use the created client for subsequent operations...

<?php

// Load dependencies from the autoload file.
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Read the AccessKey ID and AccessKey secret from environment variables.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# Load the default SDK configuration.
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider); // Set the credential provider.

$cfg->setRegion(region: "<region-id>");

# Set the connection timeout.
$cfg->setConnectTimeout(connectTimeout: 30);

# Set the read/write timeout.
$cfg->setReadwriteTimeout(readwriteTimeout:30);

// Create an OSS client instance.
$client = new Oss\Client($cfg);

// Use the created client for subsequent operations...

<?php

// Include the autoload file to ensure that dependencies are correctly loaded.
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Use EnvironmentVariableCredentialsProvider to read the AccessKey ID and AccessKey secret from environment variables.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# Load the default SDK configuration and set the credential provider.
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider);

$cfg->setRegion(region: "<region-id>");

// Set the maximum number of attempts for an HTTP request. The default value is 3.
$cfg->setRetryMaxAttempts(5);

// Create an OSS client instance.
$client = new Oss\Client($cfg);

// Use the created client for subsequent operations...

<?php

// Import the autoload file to load dependencies.
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Create a credential provider that reads the Access Key ID and Access Key Secret from environment variables.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// Load the default configuration and set the credential provider.
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider);

$cfg->setRegion(region: "<region-id>");

// Disable SSL.
$cfg->setDisableSSL(true);

// Create an OSS client instance.
$client = new Oss\Client($cfg);

// Use the client for OSS operations.

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

// Configure the OSS client.
$region = '<region-id>'; // The OSS region.
$bucket = 'bucket-name'; // The destination bucket.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider(); // Load credentials from environment variables.
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider); // Set the credential provider.
$cfg->setRegion(region: $region); // Set the region.
$cfg->setEndpoint(endpoint: 'http://oss-<region-id>.aliyuncs.com'); // Set the endpoint.

// Create an OSS client that supports coroutines.
$client = new Oss\Client(config: $cfg, options: ['handler' => HandlerStack::create(handler: new CoroutineHandler())]);

// Coroutine task 1: Upload swoole.txt.
co(function () use ($client, $bucket) {
    try {
        $key = 'swoole.txt'; // The object name.
        $data = 'Hello OSS'; // The object content.
        $request = new Oss\Models\PutObjectRequest($bucket, $key); // Create an upload request.
        $request->body = Oss\Utils::streamFor($data); // Set the request body.
        $result = $client->putObject(request: $request); // Perform the upload.
        echo "Task 1 Result:\n" . var_export($result, true) . "\n"; // Print the result.
    } catch (\Exception $e) {
        echo "Task 1 Error: " . $e->getMessage() . "\n"; // Catch the exception.
    }
});

// Coroutine task 2: Upload hyperf.txt.
co(function () use ($client, $bucket) {
    try {
        $key = 'hyperf.txt'; // The object name.
        $data = 'Hello OSS'; // The object content.
        $request = new Oss\Models\PutObjectRequest($bucket, $key); // Create an upload request.
        $request->body = Oss\Utils::streamFor($data); // Set the request body.
        $result = $client->putObject($request); // Perform the upload.
        echo "Task 2 Result:\n" . var_export($result, true) . "\n"; // Print the result.
    } catch (\Exception $e) {
        echo "Task 2 Error: " . $e->getMessage() . "\n"; // Catch the exception.
    }
});

<?php

// Include the autoload file to load dependencies correctly.
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Create a credential provider that reads the AccessKey ID and AccessKey Secret from environment variables.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# Load the default SDK config and set the credential provider.
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider);

// Method 1: Specify the region and set setUseInternalEndpoint to true.
$cfg->setRegion('<region-id>')->setUseInternalEndpoint(true);

// // Method 2: Directly specify the region and endpoint.
// // Specify the internal endpoint for the region where the bucket is located.
// // To use the HTTP protocol, set the endpoint to 'http://oss-<region-id>-internal.aliyuncs.com'.
// $cfg->setRegion('<region-id>')->setEndpoint('https://oss-<region-id>-internal.aliyuncs.com');

// Create an OSS client instance.
$client = new Oss\Client($cfg);

// Use the created client for subsequent operations...

<?php

// Load project dependencies.
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Read the AccessKey ID and AccessKey Secret from environment variables.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# Load the default SDK configuration and set the credential provider.
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider);

// Method 1: Specify the region and set setUseAccelerateEndpoint to true.
$cfg->setRegion('<region-id>')->setUseAccelerateEndpoint(true);

// // Method 2: Directly specify the region and endpoint.
// // Specify the regional acceleration endpoint.
// $cfg->setRegion('<region-id>')->setEndpoint('https://oss-accelerate.aliyuncs.com');

// Create an OSS client.
$client = new Oss\Client($cfg);

// Use this client for subsequent operations.

<?php

// Import the autoload file to load dependencies.
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Create a credential provider that reads the AccessKey ID and AccessKey Secret from environment variables.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# Load the default SDK configurations and set the credential provider.
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider);

// Specify the region and set the endpoint to your private domain.
$cfg->setRegion('<region-id>')->setEndpoint('https://service.corp.example.com');

// Create an OSS client instance.
$client = new Oss\Client($cfg);

// Use the created client for subsequent operations...

<?php

// Import the autoload file to ensure that dependencies are correctly loaded.
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Use EnvironmentVariableCredentialsProvider to read the AccessKey ID and AccessKey secret from environment variables.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

# Load the default SDK configurations and set the credential provider.
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider); // Set the credential provider.

// Specify the region where the bucket is located. For example, for China (Beijing) Alibaba Gov Cloud 1, set the region to cn-north-2-gov-1.
// Specify the internal endpoint of the bucket's region. For example, for China (Beijing) Alibaba Gov Cloud 1, set the endpoint to 'https://oss-cn-north-2-gov-1-internal.aliyuncs.com'.
// To use the HTTP protocol, set the endpoint to 'http://oss-cn-north-2-gov-1-internal.aliyuncs.com'.
$cfg->setRegion('cn-north-2-gov-1')->setEndpoint('https://oss-cn-north-2-gov-1-internal.aliyuncs.com');

// Create an OSS client instance.
$client = new Oss\Client($cfg);

// Use the created client for subsequent operations.

1. Adicione a biblioteca de credenciais da Alibaba Cloud credentials-php.

   composer require alibabacloud/credentials

2. Configure o ARN da função OIDC como credencial de acesso.

   <?php
   
   // Load dependencies from the autoload file.
   require_once 'vendor/autoload.php';
   
   use AlibabaCloud\Oss\V2 as Oss;
   use AlibabaCloud\Credentials\Credential;
   
   // Create a configuration object to define the credential type and related information.
   $config = new Credential\Config([
       // Specify the credential type. In this example, the oidc_role_arn type is used.
       'type' => 'oidc_role_arn',
   
       // Specify the ARN of the OIDC identity provider. You can also set this using the ALIBABA_CLOUD_OIDC_PROVIDER_ARN environment variable.
       'oidcProviderArn' => '<oidc_provider_arn>',  // Replace with the actual OIDC identity provider ARN.
   
       // Specify the OIDC token file path. You can also set this using the ALIBABA_CLOUD_OIDC_TOKEN_FILE environment variable.
       'oidcTokenFilePath' => '<oidc_token_file_path>',  // Replace with the actual OIDC token file path.
   
       // Specify the ARN of the RAM role. You can also set this using the ALIBABA_CLOUD_ROLE_ARN environment variable.
       'roleArn' => '<role_arn>',  // Replace with the actual RAM role ARN.
   
       // Specify the role session name. You can also set this using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
       'roleSessionName' => '<role_session_name>',  // Replace with the actual role session name.
   
       // Optional: Specify a permission policy to further restrict the RAM role's permissions.
       // Example policy: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
       'policy' => '',  // To limit permissions, replace this with the actual policy JSON string.
   
       // Optional: Specify the session validity period in seconds. The default value is 3,600 seconds.
       'roleSessionExpiration' => 3600,  // To adjust the validity period, modify this value.
   ]);
   
   // Initialize a credential instance using the configuration object.
   $credential = new Credential($config);
   
   // Load the default configurations and obtain the OSS configuration object.
   $cfg = Oss\Config::loadDefault();
   
   // Set a credential provider that uses a callback function to dynamically generate credentials.
   $cfg->setCredentialsProvider(new Oss\Credentials\CredentialsProviderFunc(function () use ($credential) {
       // Obtain the temporary credential (STS token).
       $cred = $credential->getCredential();
   
       // Return a credential object that contains the AccessKey ID, AccessKey secret, and security token.
       return new Oss\Credentials\Credentials(
           accessKeyId: $cred->getAccessKeyId(),       // The temporary AccessKey ID.
           accessKeySecret: $cred->getAccessKeySecret(), // The temporary AccessKey secret.
           securityToken: $cred->getSecurityToken()   // The security token (STS token).
       );
   }));
   
   $region = '<region-id>';
   $cfg->setRegion($region);
   
   // Create an OSS client instance.
   $client = new Oss\Client($cfg);
   
   // Use the created client for subsequent operations...

1. Por exemplo, você usa o código a seguir para baixar um arquivo que não existe.

   <?php
   
   // Import the autoload file to ensure that dependencies are correctly loaded.
   require_once __DIR__ . '/../vendor/autoload.php';
   
   use AlibabaCloud\Oss\V2 as Oss;
   
   // Define the description for command-line arguments.
   $optsdesc = [
       "region" => ['help' => 'The region in which the bucket is located.', 'required' => True], // The region where the bucket is located (required).
       "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False], // The endpoint (optional).
       "bucket" => ['help' => 'The name of the bucket', 'required' => True], // The bucket name (required).
       "key" => ['help' => 'The name of the object', 'required' => True], // The object name (required).
   ];
   
   // Convert the parameter descriptions to the long option format required by getopt.
   // A colon ":" after each parameter indicates that the parameter requires a value.
   $longopts = \array_map(function ($key) {
       return "$key:";
   }, array_keys($optsdesc));
   
   // Parse the command-line arguments.
   $options = getopt("", $longopts);
   
   // Verify that all required parameters are present.
   foreach ($optsdesc as $key => $value) {
       if ($value['required'] === True && empty($options[$key])) {
           $help = $value['help']; // Get the help information for the parameter.
           echo "Error: the following arguments are required: --$key, $help" . PHP_EOL;
           exit(1); // Exit the program if a required parameter is missing.
       }
   }
   
   // Extract values from the parsed parameters.
   $region = $options["region"]; // The region where the bucket is located.
   $bucket = $options["bucket"]; // The bucket name.
   $key = $options["key"];       // The object name.
   
   // Load credentials from environment variables.
   // Use EnvironmentVariableCredentialsProvider to read the AccessKey ID and AccessKey secret from environment variables.
   $credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();
   
   // Use the default SDK configurations.
   $cfg = Oss\Config::loadDefault();
   $cfg->setCredentialsProvider($credentialsProvider); // Set the credential provider.
   $cfg->setRegion($region); // Set the region where the bucket is located.
   if (isset($options["endpoint"])) {
       $cfg->setEndpoint($options["endpoint"]); // If an endpoint is provided, set the endpoint.
   }
   
   // Create an OSS client instance.
   $client = new Oss\Client($cfg);
   
   // Create a GetObjectRequest object to get the content of the specified object.
   $request = new Oss\Models\GetObjectRequest(bucket: $bucket, key: $key);
   
   // Perform the get object operation.
   $result = $client->getObject($request);
   
   // Define the local file path to save the content.
   $localFilePath = './test/file.txt'; // Replace with the actual file path.
   
   // Write the content to the local file.
   file_put_contents( $localFilePath, $result->body->getContents());
   
   // Print the result.
   // Output the HTTP status code, request ID, and object content.
   printf(
       'status code:' . $result->statusCode . PHP_EOL . // The HTTP status code. For example, 200 indicates success.
       'request id:' . $result->requestId . PHP_EOL  // The request ID, used for debugging or tracking requests.
   );
   

2. Exemplo de resposta de erro. O 'EC': '0026-00000001' identifica a causa específica do erro.

   teyimui@xxx 2051 get_object % php get_object_to_file.php   region cn-hangzhou   bucket xxx
   PHP Fatal error:  Uncaught AlibabaCloud\Oss\V2\Exception\ServiceException: Error returned by Service.
   Http Status Code: 404
   Error Code: NoSuchKey
   Request Id: 687F3B562C1E9331312B1F00
   Message: The specified key does not exist.
   EC: 0026-00000001
   Timestamp: Tue, 22 Jul 2025 07:18:46 GMT
   Request Endpoint: GET https://xxx.oss-cn-hangzhou.aliyuncs.com/put-php.txt in xxx

3. Diagnostique o erro usando o EC da resposta:

   1. Abra a Central de Solução de Problemas da OpenAPI.

   2. Na caixa de pesquisa, insira o EC, por exemplo, 0026-00000001. Clique em Diagnose.

   3. A página de resultados exibe a descrição do problema, a causa e a solução.