All Products
Search
Document Center

Object Storage Service:Pay-by-requester (PHP SDK V2)

Last Updated:Aug 05, 2025

In pay-by-requester mode, the requester pays for the traffic and request fees generated when data is read from a bucket, while the bucket owner pays only for storage fees. You can enable this feature for a bucket to share data without incurring charges for the requests and traffic generated when your bucket is accessed.

Usage notes

  • The sample code in this topic uses the region ID cn-hangzhou for the China (Hangzhou) region as an example. By default, a public endpoint is used. If you want to access OSS from other Alibaba Cloud products in the same region, use an internal endpoint. For more information about the mappings between OSS regions and endpoints, see Regions and endpoints.

  • To set the pay-by-requester mode, you must have the oss:PutBucketRequestPayment permission. To query the pay-by-requester mode, you must have the oss:GetBucketRequestPayment permission. For more information, see Attach a custom access policy to a RAM user.

Sample code

Set the pay-by-requester mode

You can use the following sample code to set the pay-by-requester mode.

<?php

require_once __DIR__ . '/../vendor/autoload.php'; // Import the autoloader file to load dependency libraries.

use AlibabaCloud\Oss\V2 as Oss;

// Define the descriptions for command line arguments.
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True], // The region where the bucket is located. This parameter is required. For example, oss-cn-hangzhou.
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False], // The endpoint that other services can use to access OSS. This parameter is optional.
    "bucket" => ['help' => 'The name of the bucket', 'required' => True], // The name of the bucket. This parameter is required.
];
$longopts = \array_map(function ($key) {
    return "$key:"; // Add a colon (:) after each parameter to indicate that a value is required.
}, array_keys($optsdesc));

// Parse the command line arguments.
$options = getopt("", $longopts); 

// Check whether required arguments are missing.
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help"; // Prompt the user that a required argument is missing.
        exit(1); 
    }
}

// Obtain the values of the command line arguments.
$region = $options["region"]; // The region where the bucket is located.
$bucket = $options["bucket"]; // The name of the bucket.

// Load credential information (AccessKeyId and AccessKeySecret) from environment variables.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider(); 

// Use the default configurations of the SDK.
$cfg = Oss\Config::loadDefault(); // Load the default configurations of the SDK.
$cfg->setCredentialsProvider($credentialsProvider); // Set the credential provider.
$cfg->setRegion($region); // Set the region.
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 request object to set the payment method for bucket requests.
$request = new Oss\Models\PutBucketRequestPaymentRequest(
    $bucket,
    new Oss\Models\RequestPaymentConfiguration('Requester') 
);

// Call the putBucketRequestPayment method to set the payment method for bucket requests.
$result = $client->putBucketRequestPayment($request); 

// Print the result.
printf(
    'status code:' . $result->statusCode . PHP_EOL . // The HTTP response status code.
    'request id:' . $result->requestId // The unique ID of the request.
);

Query the pay-by-requester configuration

You can use the following sample code to query the pay-by-requester configuration.

<?php

require_once __DIR__ . '/../vendor/autoload.php'; // Import the autoloader file to load dependency libraries.

use AlibabaCloud\Oss\V2 as Oss;

// Define the descriptions for command line arguments.
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True], // The region where the bucket is located. This parameter is required. For example, oss-cn-hangzhou.
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False], // The endpoint that other services can use to access OSS. This parameter is optional.
    "bucket" => ['help' => 'The name of the bucket', 'required' => True], // The name of the bucket. This parameter is required.
];
$longopts = \array_map(function ($key) {
    return "$key:"; // Add a colon (:) after each parameter to indicate that a value is required.
}, array_keys($optsdesc));

// Parse the command line arguments.
$options = getopt("", $longopts); 

// Check whether required arguments are missing.
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help"; // Prompt the user that a required argument is missing.
        exit(1); 
    }
}

// Obtain the values of the command line arguments.
$region = $options["region"]; // The region where the bucket is located.
$bucket = $options["bucket"]; // The name of the bucket.

// Load credential information (AccessKeyId and AccessKeySecret) from environment variables.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider(); 

// Use the default configurations of the SDK.
$cfg = Oss\Config::loadDefault(); // Load the default configurations of the SDK.
$cfg->setCredentialsProvider($credentialsProvider); // Set the credential provider.
$cfg->setRegion($region); // Set the region.
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 request object to query the payment method for bucket requests.
$request = new Oss\Models\GetBucketRequestPaymentRequest($bucket); 

// Call the getBucketRequestPayment method to query the payment method for bucket requests.
$result = $client->getBucketRequestPayment($request); 

// Print the result.
printf(

    'status code:' . $result->statusCode . PHP_EOL . // The HTTP response status code.
    'request id:' . $result->requestId . PHP_EOL . // The unique ID of the request.
    'request payer:' . $result->requestPaymentConfiguration->payer // The returned payment method for requests (BucketOwner or Requester).
);

References

  • For the complete sample code for setting the pay-by-requester mode, see GitHub sample.

  • For more information about the API operation for setting the pay-by-requester mode, see PutBucketRequestPayment.

  • For the complete sample code for querying the pay-by-requester configuration, see GitHub sample.

  • For more information about the API operation for querying the pay-by-requester configuration, see GetBucketRequestPayment.