List object versions with the OSS SDK for PHP V1 - Object Storage Service

List all object versions, including delete markers, in a versioning-enabled bucket. Filter results by prefix, set a maximum count, or scope the listing to a specific directory.

Prerequisites

Before you begin, make sure that you have:

A bucket with versioning enabled
The oss:ListObjectVersions permission. For details, see Grant custom permissions to a RAM user
The OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables set

Usage notes

Examples in this topic use the public endpoint for the China (Hangzhou) region. To access OSS from other Alibaba Cloud services in the same region, use an internal endpoint. For supported regions and endpoints, see Regions and endpoints.
To create an OSSClient instance with a custom domain name or Security Token Service (STS), see Create an OSSClient instance.

How it works

listObjectVersions() returns object versions per call. When a result set is truncated, the response sets IsTruncated to true and includes two continuation markers:

NextKeyMarker — the key name where the next page starts
NextVersionIdMarker — the version ID where the next page starts

Pass both markers as OSS_KEY_MARKER and OSS_VERSION_ID_MARKER in the next request to retrieve the following page. Repeat until IsTruncated is false. All paginated examples in this topic use this loop pattern.

Each call returns two separate lists:

Object versions — retrieved with getObjectVersionList()
Delete markers — retrieved with getDeleteMarkerList()

Each entry in both lists exposes getKey(), getVersionId(), and getIsLatest().

List all object versions in a bucket

The following example lists all object versions and delete markers in examplebucket, paginating through the full result set.

<?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 credentials from environment variables.
// Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running this code.
$provider = new EnvironmentVariableCredentialsProvider();

// Replace yourEndpoint with the endpoint for your bucket's region.
// Example for China (Hangzhou): https://oss-cn-hangzhou.aliyuncs.com
$endpoint = "yourEndpoint";
$bucket = "examplebucket";

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

try {
    $option = array(
        OssClient::OSS_KEY_MARKER => null,         // key-marker: start from the beginning
        OssClient::OSS_VERSION_ID_MARKER => null   // version-id-marker: start from the beginning
    );

    // Pagination loop: repeat until all versions are retrieved.
    $hasMore = true;
    while ($hasMore) {
        $result = $ossClient->listObjectVersions($bucket, $option);

        // Print object versions.
        foreach ($result->getObjectVersionList() as $info) {
            printf("key: %s\n", $info->getKey());
            printf("version ID: %s\n", $info->getVersionId());
            printf("is latest: %s\n\n", $info->getIsLatest());
        }

        // Print delete markers.
        foreach ($result->getDeleteMarkerList() as $info) {
            printf("delete marker key: %s\n", $info->getKey());
            printf("delete marker version ID: %s\n", $info->getVersionId());
            printf("delete marker is latest: %s\n\n", $info->getIsLatest());
        }

        // Advance to the next page if results are truncated.
        if ($result->getIsTruncated() === 'true') {
            $option[OssClient::OSS_KEY_MARKER] = $result->getNextKeyMarker();
            $option[OssClient::OSS_VERSION_ID_MARKER] = $result->getNextVersionIdMarker();
        } else {
            $hasMore = false;
        }
    }
} catch (OssException $e) {
    printf($e->getMessage() . "\n");
    return;
}

List object versions with a specified prefix

Set OSS_PREFIX to filter results to objects whose keys start with a given string. The following example lists all versions of objects with the test prefix.

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

$provider = new EnvironmentVariableCredentialsProvider();
$endpoint = "yourEndpoint";
$bucket = "examplebucket";

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

try {
    $option = array(
        OssClient::OSS_KEY_MARKER => null,
        OssClient::OSS_VERSION_ID_MARKER => null,
        OssClient::OSS_PREFIX => "test"   // prefix: only list objects whose keys start with "test"
    );

    // Pagination loop: repeat until all versions are retrieved.
    $hasMore = true;
    while ($hasMore) {
        $result = $ossClient->listObjectVersions($bucket, $option);

        foreach ($result->getObjectVersionList() as $info) {
            printf("key: %s\n", $info->getKey());
            printf("version ID: %s\n", $info->getVersionId());
            printf("is latest: %s\n\n", $info->getIsLatest());
        }

        foreach ($result->getDeleteMarkerList() as $info) {
            printf("delete marker key: %s\n", $info->getKey());
            printf("delete marker version ID: %s\n", $info->getVersionId());
            printf("delete marker is latest: %s\n\n", $info->getIsLatest());
        }

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

List a specified number of object versions

Set OSS_MAX_KEYS to cap the number of versions returned in a single call. The following example retrieves up to 200 versions from 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;

$provider = new EnvironmentVariableCredentialsProvider();
$endpoint = "yourEndpoint";
$bucket = "examplebucket";

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

try {
    $option = array(
        OssClient::OSS_KEY_MARKER => null,
        OssClient::OSS_VERSION_ID_MARKER => null,
        OssClient::OSS_MAX_KEYS => 200   // max-keys: return at most 200 versions per call
    );

    $result = $ossClient->listObjectVersions($bucket, $option);

    foreach ($result->getObjectVersionList() as $info) {
        printf("key: %s\n", $info->getKey());
        printf("version ID: %s\n", $info->getVersionId());
        printf("is latest: %s\n\n", $info->getIsLatest());
    }

    foreach ($result->getDeleteMarkerList() as $info) {
        printf("delete marker key: %s\n", $info->getKey());
        printf("delete marker version ID: %s\n", $info->getVersionId());
        printf("delete marker is latest: %s\n\n", $info->getIsLatest());
    }
} catch (OssException $e) {
    printf($e->getMessage() . "\n");
    return;
}

List object versions by directory

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

To scope a listing to a directory, combine OSS_DELIMITER and OSS_PREFIX:

`OSS_DELIMITER = "/"` — groups objects under each subfolder into a single CommonPrefixes entry instead of listing them individually.
`OSS_PREFIX = "<directory>/"` — limits results to objects whose keys start with the specified directory path.

List object versions in the root directory

Set OSS_DELIMITER to / with no prefix. OSS returns objects at the root level and lists each immediate subdirectory as a common prefix.

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

$provider = new EnvironmentVariableCredentialsProvider();
$endpoint = "yourEndpoint";
$bucket = "examplebucket";

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

try {
    $option = array(
        OssClient::OSS_KEY_MARKER => null,
        OssClient::OSS_VERSION_ID_MARKER => null,
        OssClient::OSS_DELIMITER => "/"   // delimiter: group objects under subdirectories into CommonPrefixes
    );

    // Pagination loop: repeat until all versions are retrieved.
    $hasMore = true;
    while ($hasMore) {
        $result = $ossClient->listObjectVersions($bucket, $option);

        foreach ($result->getObjectVersionList() as $info) {
            printf("key: %s\n", $info->getKey());
            printf("version ID: %s\n", $info->getVersionId());
            printf("is latest: %s\n\n", $info->getIsLatest());
        }

        foreach ($result->getDeleteMarkerList() as $info) {
            printf("delete marker key: %s\n", $info->getKey());
            printf("delete marker version ID: %s\n", $info->getVersionId());
            printf("delete marker is latest: %s\n\n", $info->getIsLatest());
        }

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

List object versions in a specified directory

Set both OSS_DELIMITER and OSS_PREFIX to list the contents of a specific directory. The following example lists all versions of objects in the test/ directory.

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

$provider = new EnvironmentVariableCredentialsProvider();
$endpoint = "yourEndpoint";
$bucket = "examplebucket";

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

try {
    $option = array(
        OssClient::OSS_KEY_MARKER => null,
        OssClient::OSS_VERSION_ID_MARKER => null,
        OssClient::OSS_DELIMITER => "/",    // delimiter: group objects under subdirectories into CommonPrefixes
        OssClient::OSS_PREFIX => "test/"    // prefix: list only objects in the test/ directory
    );

    // Pagination loop: repeat until all versions are retrieved.
    $hasMore = true;
    while ($hasMore) {
        $result = $ossClient->listObjectVersions($bucket, $option);

        foreach ($result->getObjectVersionList() as $info) {
            printf("key: %s\n", $info->getKey());
            printf("version ID: %s\n", $info->getVersionId());
            printf("is latest: %s\n\n", $info->getIsLatest());
        }

        foreach ($result->getDeleteMarkerList() as $info) {
            printf("delete marker key: %s\n", $info->getKey());
            printf("delete marker version ID: %s\n", $info->getVersionId());
            printf("delete marker is latest: %s\n\n", $info->getIsLatest());
        }

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