Object Storage Service:Retention policies using OSS SDK for PHP 2.0

How it works

A bucket-level retention policy follows this lifecycle:

1. Create — Set a retention period. The policy starts in an unlocked state, during which you can cancel it.

2. Lock — Lock the policy to make it permanent and compliance-grade. A locked policy cannot be deleted, and the retention period can only be extended, never shortened.

3. Query — Retrieve the current policy configuration and status at any time.

4. Extend — Increase the retention period of a locked policy.

5. Cancel — Abort the policy while it is still unlocked.

Usage notes

• The sample code uses the region ID cn-hangzhou (China (Hangzhou)). By default, a public endpoint is used. To access OSS from another Alibaba Cloud service in the same region, use an internal endpoint instead. For details, see Regions and endpoints.

• Access credentials are loaded from environment variables. For setup instructions, see Configure access credentials.

Prerequisites

Before you begin, ensure that you have:

• An OSS bucket

• The OSS SDK for PHP 2.0 installed (AlibabaCloud\Oss\V2)

• Your AccessKey ID and AccessKey secret set as environment variables

Client setup

All examples share the same client initialization. Run this block once before calling any operation.

<?php

require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Parse command-line arguments.
$optsdesc = [
    "region"   => ['help' => 'The region where the bucket is located.', 'required' => true],
    "endpoint" => ['help' => 'Custom endpoint (optional).', 'required' => false],
    "bucket"   => ['help' => 'The bucket name.', 'required' => true],
];

$longopts = array_map(fn($key) => "$key:", array_keys($optsdesc));
$options  = getopt("", $longopts);

foreach ($optsdesc as $key => $meta) {
    if ($meta['required'] && empty($options[$key])) {
        echo "Error: --$key is required. {$meta['help']}\n";
        exit(1);
    }
}

$region = $options['region'];
$bucket = $options['bucket'];

// Load credentials from environment variables.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// Initialize the client.
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion($region);

if (isset($options['endpoint'])) {
    $cfg->setEndpoint($options['endpoint']);
}

$client = new Oss\Client($cfg);

Lock a retention policy

Call completeBucketWorm to lock the policy. After locking, the policy is permanent and compliance-grade. A locked policy cannot be canceled, and the retention period can only be extended.

Required parameters:

// Add --worm-id to the argument list.
$optsdesc['worm-id'] = ['help' => 'The WORM ID of the retention policy.', 'required' => true];
$wormId = $options['worm-id'];

$request = new Oss\Models\CompleteBucketWormRequest(
    bucket: $bucket,
    wormId: $wormId
);

$result = $client->completeBucketWorm($request);

printf(
    "status code: %s\n" .
    "request ID: %s\n",
    $result->statusCode,
    $result->requestId
);

For the API specification, see CompleteBucketWorm.

Query a retention policy

Call getBucketWorm to retrieve the current policy configuration and status.

Required parameters:

$request = new Oss\Models\GetBucketWormRequest(bucket: $bucket);

$result = $client->getBucketWorm($request);

printf(
    "status code: %s\n" .
    "request ID: %s\n" .
    "WORM config: %s\n",
    $result->statusCode,
    $result->requestId,
    var_export($result->wormConfiguration, true)
);

The returned wormConfiguration contains the policy status (locked or unlocked), the WORM ID, and the retention period.

References

• InitiateBucketWorm — Create a retention policy

• CompleteBucketWorm — Lock a retention policy

• AbortBucketWorm — Cancel an unlocked retention policy

• GetBucketWorm — Query a retention policy

• ExtendBucketWorm — Extend the retention period of a retention policy