How to upload files to a versioning-enabled bucket (PHP SDK V1) - Object Storage Service

This topic describes how to upload objects to a versioning-enabled bucket.

Precautions

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 upload an object, you must have the oss:PutObject permission. For more information, see Grant custom permissions to a RAM user.

Simple upload

For a bucket with versioning enabled, OSS generates a globally unique random string as the version ID for each newly uploaded object. This ID is returned in the x-oss-version-id field of the response header.

For a bucket with versioning suspended, OSS generates a version ID of "null" for each newly uploaded object. If you upload an object with the same name, the new object overwrites the previous one. This means the object has only one version, and its ID is "null".

The following code shows how to perform a simple upload:

<?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 running this sample code, make sure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
$provider = new EnvironmentVariableCredentialsProvider();
// The Endpoint of the China (Hangzhou) region is used as an example. Replace it with the actual Endpoint.
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
$bucket= "<yourBucketName>";
// Specify the full path of the object. Do not include the bucket name. Example: example/test.txt.
$object = "<yourObjectName>";
$content = "hello world";

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

try {
    // Upload an object to a versioned bucket.
    $ret = $ossClient->putObject($bucket, $object, $content);

    // View the version information of the object.
    print("versionId:" .$ret[OssClient::OSS_HEADER_VERSION_ID]);
} catch (OssException $e) {
    printf(__FUNCTION__ . ": FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}

print(__FUNCTION__ . ": OK" . "\n");

For more information about simple uploads, see PutObject.

Append upload

When you append data to an object (AppendObject) in a versioned bucket, note the following:

You can perform an AppendObject operation only on an object whose current version is of the Appendable type.
You cannot perform an AppendObject operation on an object whose current version is not of the Appendable type, such as a Normal Object or a Delete Marker. You also cannot perform this operation if only the historical versions of the object are of the Appendable type.
When you perform an AppendObject operation on an object whose current version is of the Appendable type, OSS does not create a historical version for that object.
When you perform a PutObject or DeleteObject operation on an object whose current version is of the Appendable type, OSS saves the Appendable object as a historical version. You can no longer append data to this object.

The following code shows how to perform an append upload:

<?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 running this sample code, make sure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
$provider = new EnvironmentVariableCredentialsProvider();
// The Endpoint of the China (Hangzhou) region is used as an example. Replace it with the actual Endpoint.
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
$bucket= "<yourBucketName>";
$object = "<yourObjectName>";
// After the first, second, and third append uploads, the file content is "Hello OSS", "Hi OSS", and "OSS OK" respectively.
$content_array = array('Hello OSS', 'Hi OSS', 'OSS OK');
try{
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);

    // The first append upload. The position for the first append is 0. The return value is the position for the next append. The position for subsequent appends is the length of the file before the append.
    $position = $ossClient->appendObject($bucket, $object, $content_array[0], 0);    
    $position = $ossClient->appendObject($bucket, $object, $content_array[1], $position);   
    $position = $ossClient->appendObject($bucket, $object, $content_array[2], $position);
} catch(OssException $e) {
    printf(__FUNCTION__ . ": FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}
print(__FUNCTION__ . ": OK" . "\n");

For more information about append uploads, see AppendObject.

Multipart upload

In a versioned bucket, you can call the CompleteMultipartUpload operation to complete a multipart upload. OSS generates a unique version ID for the entire object and returns it in the x-oss-version-id field of the response header.

The following code shows how to perform a multipart upload:

<?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;
use OSS\Core\OssUtil;

// Obtain access credentials from environment variables. Before running this sample code, make sure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
$provider = new EnvironmentVariableCredentialsProvider();
// The Endpoint of the China (Hangzhou) region is used as an example. Replace it with the actual Endpoint.
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
$bucket= "<yourBucketName>";
$object = "<yourObjectName>";
// Specify the full path of the local file.
$uploadFile = "<yourLocalFile>";

/**
 *  Step 1: Initialize a multipart upload event and obtain the uploadId.
 */
try{
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);

    // The uploadId is returned. The uploadId is the unique identifier of the multipart upload event. You can use the uploadId to perform related operations, such as aborting or querying the multipart upload.
    $uploadId = $ossClient->initiateMultipartUpload($bucket, $object);
} catch(OssException $e) {
    printf(__FUNCTION__ . ": initiateMultipartUpload FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}
print(__FUNCTION__ . ": initiateMultipartUpload OK" . "\n");
/*
 * Step 2: Upload parts.
 */
$partSize = 10 * 1024 * 1024;
$uploadFileSize = sprintf('%u',filesize($uploadFile));
$pieces = $ossClient->generateMultiuploadParts($uploadFileSize, $partSize);
$responseUploadPart = array();
$uploadPosition = 0;
$isCheckMd5 = true;
foreach ($pieces as $i => $piece) {
    $fromPos = $uploadPosition + (integer)$piece[$ossClient::OSS_SEEK_TO];
    $toPos = (integer)$piece[$ossClient::OSS_LENGTH] + $fromPos - 1;
    $upOptions = array(
        // The file to upload.
        $ossClient::OSS_FILE_UPLOAD => $uploadFile,
        // Set the part number.
        $ossClient::OSS_PART_NUM => ($i + 1),
        // Specify the start position of the part to upload.
        $ossClient::OSS_SEEK_TO => $fromPos,
        // Specify the file length.
        $ossClient::OSS_LENGTH => $toPos - $fromPos + 1,
        // Specifies whether to enable MD5 validation. true: enable. false: disable.
        $ossClient::OSS_CHECK_MD5 => $isCheckMd5,
    );
    // Enable MD5 validation.
    if ($isCheckMd5) {
        $contentMd5 = OssUtil::getMd5SumForFile($uploadFile, $fromPos, $toPos);
        $upOptions[$ossClient::OSS_CONTENT_MD5] = $contentMd5;
    }
    try {
        // Upload the part.
        $responseUploadPart[] = $ossClient->uploadPart($bucket, $object, $uploadId, $upOptions);
    } catch(OssException $e) {
        printf(__FUNCTION__ . ": initiateMultipartUpload, uploadPart - part#{$i} FAILED\n");
        printf($e->getMessage() . "\n");
        return;
    }
    printf(__FUNCTION__ . ": initiateMultipartUpload, uploadPart - part#{$i} OK\n");
}
// $uploadParts is an array that consists of the ETag and part number of each part.
$uploadParts = array();
foreach ($responseUploadPart as $i => $eTag) {
    $uploadParts[] = array(
        'PartNumber' => ($i + 1),
        'ETag' => $eTag,
    );
}
/**
 * Step 3: Complete the upload.
 */
try {
    // When you call the completeMultipartUpload operation, you must provide all valid $uploadParts. After OSS receives the submitted $uploadParts, it verifies the validity of each part. After all parts are verified, OSS combines them into a complete file.
    $ret = $ossClient->completeMultipartUpload($bucket, $object, $uploadId, $uploadParts);
    // View the version information of the object.
    print("versionId:" .$ret[OssClient::OSS_HEADER_VERSION_ID]);
}  catch(OssException $e) {
    printf(__FUNCTION__ . ": completeMultipartUpload FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}
printf(__FUNCTION__ . ": completeMultipartUpload OK\n");

For more information about multipart uploads, see operations such as InitiateMultipartUpload, UploadPart, and CompleteMultipartUpload.