Configure query and modify object metadata using PHP SDK V2 - Object Storage Service

Object metadata describes the properties of an object stored in OSS. Use the OSS SDK for PHP V2 to set metadata when uploading objects, retrieve metadata without downloading object content, and update metadata on existing objects.

Key concepts

Object metadata falls into two categories:

System metadata: Managed by OSS. Includes standard HTTP headers such as Content-Type, Content-Length, ETag, and Last-Modified. Some system metadata, such as Content-Type, can be set by users at upload time.
User metadata: Custom key-value pairs you define.

Important constraint: OSS does not support in-place metadata updates. To change the metadata of an existing object, copy the object to the same or a different destination with the updated metadata using CopyObject or Copier.Copy, then set metadataDirective to REPLACE.

Prerequisites

Before you begin, ensure that you have:

An OSS bucket in your target region
The oss:PutObject permission to set metadata, or the oss:GetObject permission to query metadata. For details, see Attach a custom policy to a RAM user
Access credentials stored in environment variables (OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET)

Usage notes

The sample code uses cn-hangzhou as the region. Replace it with your actual region ID.
By default, a public endpoint is used. If you're accessing OSS from another Alibaba Cloud service in the same region, use an internal endpoint. For the full list of regions and endpoints, see Regions and endpoints.

Set metadata on upload

Set metadata on upload

Use PutObjectRequest to set metadata when uploading an object. Pass metadata as an associative array to the metadata parameter. You can configure metadata headers such as the expiration time, access control list (ACL), and user-defined metadata. The same approach applies to other upload operations.

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion('<region>');   // e.g., cn-hangzhou

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

$body = Oss\Utils::streamFor(fopen('<local-file-path>', 'r'));

$request = new Oss\Models\PutObjectRequest(
    bucket: '<bucket-name>',
    key: '<object-key>',
    metadata: [
        'Author' => 'alibaba oss sdk',   // stored as x-oss-meta-Author
        'Date'   => '2024-07-01',        // stored as x-oss-meta-Date
    ]
);
$request->body = $body;

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

printf(
    "status code: %s\n" .
    "request ID:  %s\n" .
    "ETag:        %s\n",
    $result->statusCode,   // 200 on success
    $result->requestId,
    $result->etag
);

Replace the following placeholders:

Placeholder	Description	Example
`<region>`	Region where the bucket is located	`cn-hangzhou`
`<local-file-path>`	Local path to the file to upload	`/tmp/example.txt`
`<bucket-name>`	Name of your bucket	`my-bucket`
`<object-key>`	Key (name) of the object in the bucket	`docs/example.txt`

Query object metadata

OSS provides two operations for querying metadata without downloading object content:

Operation	What it returns	Use when
`HeadObject`	All system and user metadata	You need the full set of object properties
`GetObjectMeta`	A lightweight subset of system metadata	You only need size, ETag, or timestamps

Query all metadata with HeadObject

HeadObject returns the complete metadata for an object, including all system headers and any user-defined metadata you set at upload time.

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion('<region>');

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

$request = new Oss\Models\HeadObjectRequest('<bucket-name>', '<object-key>');
$result = $client->headObject($request);

printf(
    'status code:' . $result->statusCode . PHP_EOL .
    'request id:' . $result->requestId . PHP_EOL .
    'result:' . var_export($result, true) . PHP_EOL
);

Query partial metadata with GetObjectMeta

GetObjectMeta is a lightweight alternative to HeadObject. It returns only the following six fields:

Field	Description
`ContentLength`	Object size in bytes
`ETag`	Entity tag that uniquely identifies the object version
`LastModified`	Timestamp of the last modification
`LastAccessTime`	Timestamp of the last access
`VersionId`	Version ID (if versioning is enabled)
`HashCRC64`	CRC-64 hash for data integrity verification

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion('<region>');

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

$request = new Oss\Models\GetObjectMetaRequest('<bucket-name>', '<object-key>');
$result = $client->getObjectMeta($request);

printf(
    'status code:' . $result->statusCode . PHP_EOL .
    'request id:' . $result->requestId . PHP_EOL .
    'result:' . var_export($result, true) . PHP_EOL
);

GetObjectMeta does not return user metadata or Content-Type. Use HeadObject if you need those fields.

Update metadata on an existing object

Because OSS does not support in-place metadata updates, update metadata by copying the object with metadataDirective set to REPLACE. OSS then writes the new metadata to the destination object, discarding the original metadata.

metadataDirective accepts two values:

Value	Behavior
`COPY`	Copy metadata from the source object (default)
`REPLACE`	Replace metadata with the values you specify in the request

Use CopyObject

Copy an object to the same or a different bucket and replace its metadata in one operation.

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion('<region>');

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

$request = new Oss\Models\CopyObjectRequest(
    bucket: '<destination-bucket>',
    key: '<destination-key>',
    metadata: [
        'x-oss-meta-tag1' => 'value1',
        'x-oss-meta-tag2' => 'value2',
    ],
    metadataDirective: 'Replace'   // discard source metadata, use values above
);
$request->sourceBucket = '<source-bucket>';   // omit to use the same bucket
$request->sourceKey    = '<source-key>';

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

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

Use Copier.Copy

Copier.Copy is a higher-level SDK method for copying objects while also updating metadata. You can overwrite all existing metadata with new metadata, remove the original metadata, or update only specified metadata headers. You can also specify whether to delete the source object after the copy operation is complete.

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion('<region>');

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

$copier = $client->newCopier();

$copyRequest = new Oss\Models\CopyObjectRequest(
    bucket: '<bucket-name>',
    key: '<destination-key>',
    sourceBucket: '<bucket-name>',
    sourceKey: '<source-key>'
);
$copyRequest->metadataDirective = 'REPLACE';
$copyRequest->metadata = [
    'test1' => 'val1',
    'test2' => 'value2',
];

$result = $copier->copy(request: $copyRequest);

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

To update metadata on the same object without changing its key, set <destination-key> to the same value as <source-key>.

Object Storage Service:Manage object metadata (PHP SDK V2)