How to set metadata when you upload an object (PHP SDK V1) - Object Storage Service

An object stored in Object Storage Service (OSS) consists of a key, data, and object metadata. Object metadata describes the properties of an object. It includes standard HTTP headers and user-defined metadata. You can set standard HTTP headers to define custom HTTP request policies, such as cache policies or forced download policies. You can also set user-defined metadata to identify the purpose or properties of an object.

Notes

In this topic, the public endpoint of the China (Hangzhou) region is used. To access OSS from other Alibaba Cloud services in the same region, use an internal endpoint. For details about supported 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 set object metadata, you must have the oss:PutObject permission. For more information, see Grant custom permissions to a RAM user.

Sample code

The following code shows how to set metadata when you upload an object.

Warning

If an object with the same name already exists in the bucket, it is overwritten when you set metadata during an object upload. For more information about how to prevent an object with the same name from being overwritten, see Prevent overwriting an object with the same name.

<?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 this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set. 
$provider = new EnvironmentVariableCredentialsProvider();
// Replace yourEndpoint with the endpoint of the region where the bucket is located. For example, for the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
$endpoint = "yourEndpoint";
// Specify the bucket name. Example: examplebucket.
$bucket= "examplebucket";
// Specify the full path of the object. The full path cannot contain the bucket name. Example: exampledir/exampleobject.txt.
$object = "exampledir/exampleobject.txt";
$content = file_get_contents(__FILE__);
$options = array(
    OssClient::OSS_HEADERS => array(
        'Expires' => '2012-10-01 08:00:00',
        'Content-Disposition' => 'attachment; filename="xxxxxx"',
        'x-oss-meta-self-define-title' => 'user-defined meta info',
    ));
try{
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);
    // Set metadata when you upload the object.
    $ossClient->putObject($bucket, $object, $content, $options);
} catch(OssException $e) {
    printf(__FUNCTION__ . ": FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}
print(__FUNCTION__ . ": OK" . "\n");

References

For the complete sample code that shows how to set metadata when you upload an object, see GitHub.
For more information about the API operation that you can call to set metadata when you upload an object, see PutObject.

FAQ

How do I prevent overwriting an object with the same name when I upload an object and set its metadata?

To prevent an object with the same name from being overwritten in the bucket, use one of the following methods:

Enable versioning
After you enable versioning, overwritten objects in the bucket are saved as historical versions. You can restore a historical version at any time. For more information, see Enable versioning.
Include a parameter in the upload request to prevent overwriting
Include the x-oss-forbid-overwrite parameter in the header of the upload request and set its value to true. If you upload an object that has the same name as an existing object in the bucket, the upload fails and a FileAlreadyExists error is returned. For more information, see PutObject.