List buckets using PHP SDK V1 - Object Storage Service

Use the OSS PHP SDK V1 to list buckets in your Alibaba Cloud account across all regions, with optional filters for prefix, marker, and result count.

The underlying API operation is ListBuckets (GetService).

Prerequisites

Before you begin, ensure that you have:

The OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables set with valid access credentials
The oss:ListBuckets permission. For details, see Grant a custom access policy to a RAM user

Parameters

listBuckets() accepts an optional $options array to filter results. All parameters are optional.

Parameter	Constant	Type	Description
`prefix`	`OssClient::OSS_PREFIX`	string	Return only buckets whose names start with this value
`marker`	`OssClient::OSS_MARKER`	string	Return only buckets whose names come alphabetically after this value. Use with `max-keys` to paginate.
`max-keys`	`OssClient::OSS_MAX_KEYS`	integer	Maximum number of buckets to return per call. Maximum value: 1,000. Default: 100.

Important

Always use pagination (marker + max-keys) for accounts with many buckets. A single unpaginated call returns at most 1,000 buckets and may not include all results.

The method returns a BucketListInfo object. Call getBucketList() to get the list of bucket objects. Each bucket object exposes:

Method	Return value
`getLocation()`	Region ID
`getName()`	Bucket name
`getCreatedate()`	Bucket creation date

Client setup

All examples below use the same client 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\CoreOssException;

// Load access credentials from environment variables.
$provider = new EnvironmentVariableCredentialsProvider();

// Replace the endpoint with the one for your region.
// This example uses the public endpoint for China (Hangzhou).
// Use an internal endpoint when accessing OSS from other Alibaba Cloud services in the same region.
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";

$config = [
    "provider"         => $provider,
    "endpoint"         => $endpoint,
    "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
    "region"           => "cn-hangzhou",
];
$ossClient = new OssClient($config);

For supported regions and endpoints, see Regions and endpoints. To create an OssClient instance with a custom domain or Security Token Service (STS), see Create an OSSClient instance.

List all buckets

Buckets are returned in alphabetical order.

try {
    $bucketListInfo = $ossClient->listBuckets();
} catch (OssException $e) {
    printf(__FUNCTION__ . ": FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}

$bucketList = $bucketListInfo->getBucketList();
foreach ($bucketList as $bucket) {
    print($bucket->getLocation() . "\t" . $bucket->getName() . "\t" . $bucket->getCreatedate() . "\n");
}

List buckets by prefix

Returns only buckets whose names start with the specified prefix.

// prefix: string. Only buckets whose names start with this value are returned.
$prefix = "example";

try {
    $options = [OssClient::OSS_QUERY_STRING => [OssClient::OSS_PREFIX => $prefix]];
    $bucketListInfo = $ossClient->listBuckets($options);
} catch (OssException $e) {
    printf(__FUNCTION__ . ": FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}

$bucketList = $bucketListInfo->getBucketList();
foreach ($bucketList as $bucket) {
    print($bucket->getLocation() . "\t" . $bucket->getName() . "\t" . $bucket->getCreatedate() . "\n");
}
// Returns only buckets whose names start with "example".

List buckets after a marker

Returns only buckets whose names come alphabetically after the specified marker. Use this to paginate through large result sets.

// marker: string. Results include only buckets alphabetically after this name.
$marker = "examplebucket";

try {
    $options = [OssClient::OSS_QUERY_STRING => [OssClient::OSS_MARKER => $marker]];
    $bucketListInfo = $ossClient->listBuckets($options);
} catch (OssException $e) {
    printf(__FUNCTION__ . ": FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}

$bucketList = $bucketListInfo->getBucketList();
foreach ($bucketList as $bucket) {
    print($bucket->getLocation() . "\t" . $bucket->getName() . "\t" . $bucket->getCreatedate() . "\n");
}
// Returns only buckets whose names come after "examplebucket" alphabetically.

Limit the number of returned buckets

Returns up to max-keys buckets per call. Use this to control page size when paginating.

// max-keys: integer. Maximum number of buckets to return per call.
// Maximum value: 1,000. Default: 100.
try {
    $options = [OssClient::OSS_QUERY_STRING => [OssClient::OSS_MAX_KEYS => 500]];
    $bucketListInfo = $ossClient->listBuckets($options);
} catch (OssException $e) {
    printf(__FUNCTION__ . ": FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}

$bucketList = $bucketListInfo->getBucketList();
foreach ($bucketList as $bucket) {
    print($bucket->getLocation() . "\t" . $bucket->getName() . "\t" . $bucket->getCreatedate() . "\n");
}
// Returns up to 500 buckets per call.

What's next

For the complete sample code, see the GitHub example
For API details, see ListBuckets (GetService)