All Products
Search
Document Center

Object Storage Service:List objects by using OSS SDK for PHP

Last Updated:Mar 12, 2024

This topic describes how to list objects in a versioning-enabled bucket, such as listing all objects, a specified number of objects, and objects whose names contain a specified prefix.

Usage notes

  • In this topic, the public endpoint of the China (Hangzhou) region is used. If you want to access OSS from other Alibaba Cloud services in the same region as OSS, use an internal endpoint. For more information about OSS regions and endpoints, see Regions and endpoints.

  • In this topic, an OSSClient instance is created by using an OSS endpoint. If you want to create an OSSClient instance by using custom domain names or Security Token Service (STS), see Create an OSSClient instance.

  • To list objects, you must have the oss:ListObjectVersions permission. For more information, see Attach a custom policy to a RAM user.

Lists the versions of all objects in a bucket

The following code provides an example on how to list the versions of all objects including delete markers in a bucket named examplebucket:

<?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 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 = "yourEndpoint";
// Specify the name of the bucket. Example: examplebucket. 
$bucket= "examplebucket";

$config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
    );
    $ossClient = new OssClient($config);

try{
    $option = array(
        OssClient::OSS_KEY_MARKER => null,
        OssClient::OSS_VERSION_ID_MARKER => null
    );
    $bool = true;
    while ($bool){
        $result = $ossClient->listObjectVersions($bucket,$option);
        // Display information about the listed versions of the objects. 
        foreach ($result->getObjectVersionList() as $key => $info){
            printf("key name: {$info->getKey()}\n");
            printf("versionid: {$info->getVersionId()}\n");
            printf("Is latest: {$info->getIsLatest()}\n\n");
        }

        // Display information about the listed versions of the delete markers. 
        foreach ($result->getDeleteMarkerList() as $key => $info){
            printf("del_maker key name: {$info->getKey()}\n");
            printf("del_maker versionid: {$info->getVersionId()}\n");
            printf("del_maker Is latest: {$info->getIsLatest()}\n\n");
        }

        if($result->getIsTruncated() === 'true'){
            $option[OssClient::OSS_KEY_MARKER] = $result->getNextKeyMarker();
        $option[OssClient::OSS_VERSION_ID_MARKER] = $result->getNextVersionIdMarker();
        }else{
            $bool = false;
        }
    }
} catch(OssException $e) {
    printf($e->getMessage() . "\n");
    return;
}

List the versions of the objects whose names contain a specific prefix

The following code provides an example on how to list the versions of objects whose names contain the test prefix in a bucket named examplebucket:

<?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 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 = "yourEndpoint";
// Specify the name of the bucket. Example: examplebucket. 
$bucket= "examplebucket";

$config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
    );
    $ossClient = new OssClient($config);

try{
    $option = array(
        OssClient::OSS_KEY_MARKER => null,
        OssClient::OSS_VERSION_ID_MARKER => null,
        // Specify that all versions of objects whose names contain the test prefix are listed. 
        OssClient::OSS_PREFIX => "test"
    );
    $bool = true;
    while ($bool){
        $result = $ossClient->listObjectVersions($bucket,$option);
        // Display information about the listed versions of the objects. 
        foreach ($result->getObjectVersionList() as $key => $info){
            printf("key name: {$info->getKey()}\n");
            printf("versionid: {$info->getVersionId()}\n");
            printf("Is latest: {$info->getIsLatest()}\n\n");
        }

        // Display information about the listed versions of the delete markers. 
        foreach ($result->getDeleteMarkerList() as $key => $info){
            printf("del_maker key name: {$info->getKey()}\n");
            printf("del_maker versionid: {$info->getVersionId()}\n");
            printf("del_maker Is latest: {$info->getIsLatest()}\n");
        }

        if($result->getIsTruncated() === 'true'){
            $option[OssClient::OSS_KEY_MARKER] = $result->getNextKeyMarker();
            $option[OssClient::OSS_VERSION_ID_MARKER] = $result->getNextVersionIdMarker();
        }else{
            $bool = false;
        }
    }
} catch(OssException $e) {
    printf($e->getMessage() . "\n");
    return;
}

List a specific number of object versions

The following code provides an example on how to list a specific number of object versions in a bucket named examplebucket:

<?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 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 = "yourEndpoint";
// Specify the name of the bucket. Example: examplebucket. 
$bucket= "examplebucket";

$config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
    );
    $ossClient = new OssClient($config);

try{
    $option = array(
        OssClient::OSS_KEY_MARKER => null,
        OssClient::OSS_VERSION_ID_MARKER => null,
        OssClient::OSS_MAX_KEYS => 200   // Specify that the maximum number of object versions that can be listed is 200. 
    );
    $result = $ossClient->listObjectVersions($bucket,$option);
    // Display information about the listed versions of the objects. 
    foreach ($result->getObjectVersionList() as $key => $info){
        printf("key name: ".$info->getKey().PHP_EOL);
        printf("versionid: ".$info->getVersionId().PHP_EOL);
        printf("Is latest: ".$info->getIsLatest().PHP_EOL.PHP_EOL);
    }

    // Display information about the listed versions of the delete markers. 
    foreach ($result->getDeleteMarkerList() as $key => $info){
        printf("del_maker key name: ".$info->getKey().PHP_EOL);
        printf("del_maker versionid: ".$info->getVersionId().PHP_EOL);
        printf("del_maker Is latest: ".$info->getIsLatest().PHP_EOL.PHP_EOL);
    }
} catch(OssException $e) {
    printf($e->getMessage() . "\n");
    return;
}

List objects by directory

OSS uses a flat structure to store objects. A directory is a zero-byte object whose name ends with a forward slash (/). You can upload and download this object. By default, objects whose names end with a forward slash (/) are displayed as folders in the OSS console.

You can specify the delimiter and prefix parameters in the request to list objects by directory.

  • If you set prefix to a directory name in the request, objects and subdirectories whose names contain the prefix are listed.

  • If you specify a prefix and set delimiter to a forward slash (/) in the request, objects and subdirectories whose names start with the specified prefix in the directory are listed. Each subdirectory is listed as a single result element in CommonPrefixes. The objects and directories in these subdirectories are not listed.

  • List the versions of objects in the root directory of a bucket

    The following code provides an example on how to list the versions of objects in the root directory of a bucket named examplebucket:

    <?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 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 = "yourEndpoint";
    // Specify the name of the bucket. Example: examplebucket. 
    $bucket= "examplebucket";
    
    $config = array(
            "provider" => $provider,
            "endpoint" => $endpoint,
        );
        $ossClient = new OssClient($config);
    
    try{
        $option = array(
            OssClient::OSS_KEY_MARKER => null,
            OssClient::OSS_VERSION_ID_MARKER => null,
            OssClient::OSS_DELIMITER => "/",    // Specify that the delimiter is a forward slash (/). 
        );
        $bool = true;
        while ($bool){
            $result = $ossClient->listObjectVersions($bucket,$option);
            // Display information about the listed versions of the objects. 
            foreach ($result->getObjectVersionList() as $key => $info){
                printf("key name: {$info->getKey()}\n");
                printf("versionid: {$info->getVersionId()}\n");
                printf("Is latest: {$info->getIsLatest()}\n\n");
            }
    
            // Display information about the listed versions of the delete markers. 
            foreach ($result->getDeleteMarkerList() as $key => $info){
                printf("del_maker key name: {$info->getKey()}\n");
                printf("del_maker versionid: {$info->getVersionId()}\n");
                printf("del_maker Is latest: {$info->getIsLatest()}\n\n");
            }
    
            if($result->getIsTruncated() === 'true'){
                $option[OssClient::OSS_KEY_MARKER] = $result->getNextKeyMarker();
                $option[OssClient::OSS_VERSION_ID_MARKER] = $result->getNextVersionIdMarker();
            }else{
                $bool = false;
            }
        }
    } catch(OssException $e) {
        printf($e->getMessage() . "\n");
        return;
    }                   
  • List the versions of objects in a specific directory of a bucket

    The following code provides an example on how to list the versions of objects in the test directory of a bucket named examplebucket:

    <?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 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 = "yourEndpoint";
    // Specify the name of the bucket. Example: examplebucket. 
    $bucket= "examplebucket";
    
    $config = array(
            "provider" => $provider,
            "endpoint" => $endpoint,
        );
        $ossClient = new OssClient($config);
    
    try{
        $option = array(
            OssClient::OSS_KEY_MARKER => null,
            OssClient::OSS_VERSION_ID_MARKER => null,
            OssClient::OSS_DELIMITER => "/",    // Specify that the delimiter is a forward slash (/). 
            OssClient::OSS_PREFIX => "test/",   // Specify that the versions of objects in the test directory are listed. 
        );
        $bool = true;
        while ($bool){
            $result = $ossClient->listObjectVersions($bucket,$option);
            // Display information about the listed versions of the objects. 
            foreach ($result->getObjectVersionList() as $key => $info){
                printf("key name: {$info->getKey()}\n");
                printf("versionid: {$info->getVersionId()}\n");
                printf("Is latest: {$info->getIsLatest()}\n\n");
            }
    
            // Display information about the listed versions of the delete markers. 
            foreach ($result->getDeleteMarkerList() as $key => $info){
                printf("del_maker key name: {$info->getKey()}\n");
                printf("del_maker versionid: {$info->getVersionId()}\n");
                printf("del_maker Is latest: {$info->getIsLatest()}\n\n");
            }
    
            if($result->getIsTruncated() === 'true'){
                $option[OssClient::OSS_KEY_MARKER] = $result->getNextKeyMarker();
                $option[OssClient::OSS_VERSION_ID_MARKER] = $result->getNextVersionIdMarker();
            }else{
                $bool = false;
            }
        }
    } catch(OssException $e) {
        printf($e->getMessage() . "\n");
        return;
    }