How to manage symbolic links of objects by using OSS SDK for PHP V2-Object Storage Service(OSS)-阿里云帮助中心

A symbolic link points to a target object in a bucket without duplicating it — similar to a shortcut. In a versioning-enabled bucket, each symbolic link can have multiple versions, and different versions can point to different target objects.

This topic shows how to create and retrieve symbolic links in a versioning-enabled bucket using the OSS SDK for PHP V2.

Prerequisites

Before you begin, ensure that you have:

A versioning-enabled OSS bucket
The oss:PutObject permission to create a symbolic link, or the oss:GetObject permission to retrieve one. For details, see Grant custom permissions to a RAM user

Usage notes

The sample code uses the China (Hangzhou) region (cn-hangzhou) with a public endpoint. To access OSS from other Alibaba Cloud services in the same region, use an internal endpoint. For region-to-endpoint mappings, see OSS regions and endpoints.

Create a symbolic link

A symbolic link can have multiple versions, and each version can point to a different target object. When you create a symbolic link in a versioning-enabled bucket, OSS automatically generates a version ID and returns it in the x-oss-version-id response header. You cannot create a symbolic link for a delete marker in a versioning-enabled bucket.

The following code creates a symbolic link that points to the current version of the target object.

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

// Define command-line arguments.
$optsdesc = [
    "region"   => ['help' => 'The region where the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The endpoint used to access OSS.',        'required' => False],
    "bucket"   => ['help' => 'The name of the bucket.',                 'required' => True],
    "key"      => ['help' => 'The name of the symbolic link.',          'required' => True],
    "symlink"  => ['help' => 'The name of the target object.',          'required' => True],
];

$longopts = \array_map(function ($key) { return "$key:"; }, array_keys($optsdesc));
$options  = getopt("", $longopts);

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

$region  = $options["region"];
$bucket  = $options["bucket"];
$key     = $options["key"];      // Name of the symbolic link.
$symlink = $options["symlink"];  // Name of the target object.

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

$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion($region);
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

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

// Create the symbolic link.
$request = new Oss\Models\PutSymlinkRequest(
    bucket: $bucket,
    key:    $key,      // Name of the symbolic link.
    target: $symlink,  // Name of the target object.
);

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

// Print key result fields.
printf(
    'status code: %s' . PHP_EOL .
    'request ID:  %s' . PHP_EOL .
    'version ID:  %s' . PHP_EOL,  // Version ID of the symbolic link, returned in x-oss-version-id.
    $result->statusCode,
    $result->requestId,
    $result->versionId
);

Retrieve a symbolic link

To retrieve a symbolic link, you must have the read permission on the symbolic link. By default, GetSymlink retrieves the current version of a symbolic link. Specify a version ID to retrieve a specific version. If the current version is a delete marker, OSS returns a 404 Not Found error with the x-oss-delete-marker header set to true and the x-oss-version-id header returned.

The following code retrieves a symbolic link by version ID.

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

// Define command-line arguments.
$optsdesc = [
    "region"   => ['help' => 'The region where the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The endpoint used to access OSS.',        'required' => False],
    "bucket"   => ['help' => 'The name of the bucket.',                 'required' => True],
    "key"      => ['help' => 'The name of the symbolic link.',          'required' => True],
];

$longopts = \array_map(function ($key) { return "$key:"; }, array_keys($optsdesc));
$options  = getopt("", $longopts);

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

$region = $options["region"];
$bucket = $options["bucket"];
$key    = $options["key"];  // Name of the symbolic link.

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

$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion($region);
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

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

// Retrieve the symbolic link. Specify a version ID to get a specific version.
$request = new Oss\Models\GetSymlinkRequest(
    bucket:    $bucket,
    key:       $key,
    versionId: "yourVersionId",  // Replace with the actual version ID.
);

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

// Print key result fields.
printf(
    'status code:   %s' . PHP_EOL .
    'request ID:    %s' . PHP_EOL .
    'version ID:    %s' . PHP_EOL .  // Version ID of the retrieved symbolic link.
    'target object: %s' . PHP_EOL,   // Name of the object the symbolic link points to.
    $result->statusCode,
    $result->requestId,
    $result->versionId,
    $result->target
);

Replace yourVersionId with the actual version ID. To retrieve the current version, remove the versionId parameter.