tencent cloud

Cloud Object Storage

ドキュメントCloud Object Storage

Getting Started

ダウンロード
フォーカスモード
フォントサイズ
最終更新日: 2026-06-18 10:46:02

Relevant Resources

Download address for the COS XML PHP SDK source code: XML PHP SDK.
Quick download address for the SDK: XML PHP SDK.
Demo program address: PHP sample.
For all example code in the SDK documentation, see SDK Code Samples.
For the SDK change log, see CHANGELOG.
For SDK frequently asked questions, see: PHP SDK FAQ.

Environment Configuration and Preparation

Version requirements: PHP 5.6 or later.
Note:
You can check the current PHP version by using the php -v command.
If your PHP version is 5.3 or later but earlier than 5.6, use the v1.3 version.
Required extensions: cURL extension, xml extension, dom extension, mbstring extension, json extension.
Note:
You can check whether the above extensions have been installed by using the php -m command.
Examples of commands for installing extensions in different systems are as follows:
In Ubuntu systems, you can use the apt-get package manager to install the relevant PHP extensions. The installation commands are as follows.
sudo apt-get install php-curl php-xml php-dom php-mbstring php-json
In CentOS systems, you can use the yum package manager to install the cURL extension for PHP.
sudo yum install php-curl php-xml php-dom php-mbstring php-json

Installing the SDK

The SDK can be installed in three ways: via Composer, via Phar, or from source code.
Composer Method
Phar Method
Source Code Method
It is recommended that Composer be used to install cos-php-sdk-v5. Composer is a dependency management tool for PHP that allows you to declare the dependencies required by your project and then automatically install them into your project.
Note:
You can find more information about how to install Composer, configure auto-loading, and other best practices for defining dependencies on the Composer Official Website.
1. Open the terminal.
2. Run the following command to download Composer.
curl -sS https://getcomposer.org/installer | php
3. Create a file named composer.json with the following content.
{
 "require": {
     "qcloud/cos-sdk-v5": ">=2.0"
 }
}
4. Run the following command to install using Composer.
php composer.phar install
After this command is used, a vendor folder will be created in the current directory, which contains the SDK's dependent libraries and an autoload.php script for easy calling in the project.
Note:
Composer now supports downloading either Guzzle6 or Guzzle7 based on the current PHP version. The Guzzle7 version supports the laravel8 framework. When the PHP version is 7.2.5 or above, the Guzzle7 version is downloaded automatically; otherwise, the Guzzle6 version is downloaded.
5. Call cos-php-sdk-v5 via the autoloader script by including the autoload.php file in your code.
require '/path/to/sdk/vendor/autoload.php';

Running Environment

Operating System: Ubuntu 24.04.3 LTS / x86_64
Runtime Version: PHP 8.3.6 (cli) (built: Jul 14 2025 18:30:55) (NTS)
Note:
After composer installation, the path here must be changed to the path corresponding to the autoload.php file; otherwise, the relevant methods cannot be called. If your installation path is /Users/username/project, the path referenced in the project should be filled in as /Users/username/project/vendor/autoload.php.
At this point, your project can use the COS XML PHP SDK.
1. On GitHub releases page, download the corresponding phar file.
Note:
When the PHP version is 5.6 or above and below 7.2.5, download cos-sdk-v5-6.phar and use the Guzzle6 version.
When the PHP version is 7.2.5 or above, download cos-sdk-v5-7.phar and use the Guzzle7 version.
2. Include the phar file in your code.
require '/path/to/cos-sdk-v5-x.phar';
1. Download the cos-sdk-v5.tar.gz compressed file from the SDK download page.
Note:
When the PHP version is 5.6 or above and below 7.2.5, download cos-sdk-v5-6.tar.gz and use the Guzzle6 version.
When the PHP version is 7.2.5 or above, download cos-sdk-v5-7.tar.gz and use the Guzzle7 version.
2. After decompression, load the SDK via the autoload.php script by including the autoload.php file in your code.
require '/path/to/sdk/vendor/autoload.php';
Note:
The Source code archive is the code package packaged by GitHub by default and does not contain the vendor directory. Please download the release package (the cos-sdk-v5-x.tar.gz package) instead of the Source package, and do not clone the entire repository directly. Otherwise, the index.php file and the vendor package will be missing.

Initialize COS Service

This section describes how to use the COS PHP SDK to initialize a client, create a bucket, list buckets, upload an object, list objects, download an object, and delete an object. For parameter descriptions in the examples, see the Bucket Operations and Object Operations documentation.

Initialize COS

Note:
It is recommended that users call the SDK using sub-account keys + environment variables to enhance security. When authorizing sub-accounts, please follow the principle of least privilege to prevent leakage of resources beyond the target bucket or objects.
If you must use permanent keys, it is recommended to follow the principle of least privilege to restrict the scope of permissions for the permanent keys.
Temporary Keys
Permanent Keys
If you initialize with a temporary key, create an instance using the following method.
$tmpSecretId = "TmpSecretId"; // SecretId of the temporary key. For guidance on generating and using temporary keys, see https://www.tencentcloud.com/document/product/436/14048
$tmpSecretKey = "TmpSecretKey"; // SecretKey of the temporary key. For guidance on generating and using temporary keys, see https://www.tencentcloud.com/document/product/436/14048
$tmpToken = "TmpToken"; // Token of the temporary key. For guidance on generating and using temporary keys, see https://www.tencentcloud.com/document/product/436/14048
$region = "ap-beijing"; // Replace with your region. The region of the created bucket can be viewed in the console: https://console.tencentcloud.com/cos5/bucket
$cosClient = new Qcloud\\Cos\\Client(
    array(
        'region' => $region,
        'scheme' => 'https', // Protocol header, which defaults to http
        'credentials'=> array(
            'secretId'  => $tmpSecretId,
            'secretKey' => $tmpSecretKey,
            'token' => $tmpToken)));

Running Environment

Operating System: Ubuntu 24.04.3 LTS / x86_64
Runtime Version: PHP 8.3.6 (cli) (built: Jul 14 2025 18:30:55) (NTS)
If you initialize the COSClient with a permanent key, you can first obtain the SecretId and SecretKey on the API Key Management page in the CAM console. Permanent keys are suitable for most application scenarios.
// Log in to the CAM console to view and manage SECRETID and SECRETKEY.
$secretId = getenv('COS_SECRET_ID'); // User's SecretId. It is recommended to use a sub-account key; authorization follows the principle of least privilege to reduce usage risks. For obtaining sub-account keys, refer to https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$secretKey = getenv('COS_SECRET_KEY'); // User's SecretKey. It is recommended to use a sub-account key; authorization follows the principle of least privilege to reduce usage risks. For obtaining sub-account keys, refer to https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$region = "ap-beijing"; // Your region. The region of the created bucket can be viewed in the console: https://console.tencentcloud.com/cos5/bucket
$cosClient = new Qcloud\\Cos\\Client(
    array(
        'region' => $region,
        'scheme' => 'https', // Protocol header, which defaults to http
        'credentials'=> array(
            'secretId'  => $secretId ,
            'secretKey' => $secretKey)));
Note:
If no HTTPS certificate is configured, you need to delete the scheme parameter or enter 'scheme' => 'http'. If you enter https, a certificate problem will occur. If you need to configure a certificate, see PHP SDK FAQ.

Access COS Service

Create a bucket
Querying the Bucket List
PUT Object
Querying the Object List
Downloading an Object
Delete an object
After determining the region and bucket name, refer to the following example to create a bucket. For complete examples of bucket creation, go to GitHub.
require dirname(__FILE__) . '/../vendor/autoload.php';

$secretId = getenv('COS_SECRET_ID'); // User's SecretId. It is recommended to use a sub-account key; authorization follows the principle of least privilege to reduce usage risks. For obtaining sub-account keys, refer to https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$secretKey = getenv('COS_SECRET_KEY'); // User's SecretKey. It is recommended to use a sub-account key; authorization follows the principle of least privilege to reduce usage risks. For obtaining sub-account keys, refer to https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$region = getenv('COS_REGION'); // Your region. The region of the created bucket can be viewed in the console: https://console.tencentcloud.com/cos5/bucket
$cosClient = new Qcloud\\Cos\\Client(
    array(
        'region' => $region,
        'scheme' => 'https', // Protocol header, which defaults to http
        'credentials'=> array(
            'secretId'  => $secretId,
            'secretKey' => $secretKey)));

try {
    $bucket = "examplebucket-1250000000"; // Bucket name format: BucketName-APPID.
    $result = $cosClient->createBucket(array('Bucket' => $bucket));
    //Request succeeded
    print_r($result);
} catch (\\Exception $e) {
    //Request failed
    echo($e);
}
To query the user's bucket list, refer to the following example. For complete examples of bucket list queries, go to GitHub.
require dirname(__FILE__) . '/../vendor/autoload.php';

$secretId = getenv('COS_SECRET_ID'); // User's SecretId. It is recommended to use a sub-account key; authorization follows the principle of least privilege to reduce usage risks. For obtaining sub-account keys, refer to https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$secretKey = getenv('COS_SECRET_KEY'); // User's SecretKey. It is recommended to use a sub-account key; authorization follows the principle of least privilege to reduce usage risks. For obtaining sub-account keys, refer to https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$region = getenv('COS_REGION'); // Your region. The region of the created bucket can be viewed in the console: https://console.tencentcloud.com/cos5/bucket
$cosClient = new Qcloud\\Cos\\Client(
    array(
        'region' => $region,
        'scheme' => 'https', // Protocol header, which defaults to http
        'credentials'=> array(
            'secretId'  => $secretId,
            'secretKey' => $secretKey)));

try {
    //Request succeeded
    $result = $cosClient->listBuckets();
    // Print bucket list information
    if (isset($result['Buckets'])) {
        foreach ($result['Buckets'] as $bucket) {
            echo "BucketName: " . $bucket['Name'] . "\\n";
            echo "Location: " . $bucket['Location'] . "\\n";
            echo "CreationDate: " . $bucket['CreationDate'] . "\\n";
            echo "---\\n";
        }
    }
} catch (\\Exception $e) {
    //Request failed
    echo($e);
}
For complete examples of object uploads, go to GitHub.
Note:
Use the putObject API to upload files (maximum 5G).
Use the Upload API to upload files in parts. The Upload API is a composite upload interface that performs simple uploads for small files and multipart uploads for large files.
For parameter descriptions, refer to the Upload Object documentation.
require dirname(__FILE__) . '/../vendor/autoload.php';

$secretId = getenv('COS_SECRET_ID'); // User's SecretId. It is recommended to use a sub-account key; authorization follows the principle of least privilege to reduce usage risks. For obtaining sub-account keys, refer to https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$secretKey = getenv('COS_SECRET_KEY'); // User's SecretKey. It is recommended to use a sub-account key; authorization follows the principle of least privilege to reduce usage risks. For obtaining sub-account keys, refer to https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$region = getenv('COS_REGION'); // Your region. The region of the created bucket can be viewed in the console: https://console.tencentcloud.com/cos5/bucket
$cosClient = new Qcloud\\Cos\\Client(
    array(
        'region' => $region,
        'scheme' => 'https', // Protocol header, which defaults to http
        'credentials'=> array(
            'secretId'  => $secretId,
            'secretKey' => $secretKey)));

# Upload documents.
## putObject (upload API, supporting files up to 5 GB).
### Upload strings in the memory.
try {
    $bucket = "examplebucket-1250000000"; // Bucket name format: BucketName-APPID.
    $key = "exampleobject"; // Here, key is the object key, which is the unique identifier of an object in the bucket.
    $result = $cosClient->putObject(array(
        'Bucket' => $bucket,
        'Key' => $key,
        'Body' => 'Hello World!'));
    print_r($result);
} catch (\\Exception $e) {
    echo "$e\\n";
}

### Upload file streams.
try {
    $bucket = "examplebucket-1250000000"; // Bucket name format: BucketName-APPID.
    $key = "exampleobject"; // Here, key is the object key, which is the unique identifier of an object in the bucket.
    $srcPath = "path/to/localFile"; // absolute path of the local file
    $file = fopen($srcPath, "rb");
    if ($file) {
        $result = $cosClient->putObject(array(
            'Bucket' => $bucket,
            'Key' => $key,
            'Body' => $file));
        print_r($result);
    }
} catch (\\Exception $e) {
    echo "$e\\n";
}

## Upload (advanced upload API. By default, multipart upload is used, and files up to 50 TB are supported.)
### Upload strings in the memory.
try {    
    $bucket = "examplebucket-1250000000"; // Bucket name format: BucketName-APPID.
    $key = "exampleobject"; // Here, key is the object key, which is the unique identifier of an object in the bucket.
    $result = $cosClient->Upload(
        $bucket = $bucket,
        $key = $key,
        $body = 'Hello World!');
    print_r($result);
} catch (\\Exception $e) {
    echo "$e\\n";
}

### Upload file streams.
try {    
    $bucket = "examplebucket-1250000000"; // Bucket name format: BucketName-APPID.
    $key = "exampleobject"; // Here, key is the object key, which is the unique identifier of an object in the bucket.
    $srcPath = "path/to/localFile"; // absolute path of the local file
    $file = fopen($srcPath, 'rb');
    if ($file) {
        $result = $cosClient->Upload(
            $bucket = $bucket,
            $key = $key,
            $body = $file);
    }
    print_r($result);
} catch (\\Exception $e) {
    echo "$e\\n";
}
To query the object list in a bucket, refer to the following example. For complete examples of object list queries, go to GitHub.
require dirname(__FILE__) . '/../vendor/autoload.php';

$secretId = getenv('COS_SECRET_ID'); // User's SecretId. It is recommended to use a sub-account key; authorization follows the principle of least privilege to reduce usage risks. For obtaining sub-account keys, refer to https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$secretKey = getenv('COS_SECRET_KEY'); // User's SecretKey. It is recommended to use a sub-account key; authorization follows the principle of least privilege to reduce usage risks. For obtaining sub-account keys, refer to https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$region = getenv('COS_REGION'); // Your region. The region of the created bucket can be viewed in the console: https://console.tencentcloud.com/cos5/bucket
$cosClient = new Qcloud\\Cos\\Client(
    array(
        'region' => $region,
        'scheme' => 'https', // Protocol header, which defaults to http
        'credentials'=> array(
            'secretId'  => $secretId,
            'secretKey' => $secretKey)));

try {
    $bucket = "examplebucket-1250000000"; // Bucket name format: BucketName-APPID.
    $result = $cosClient->listObjects(array(
        'Bucket' => $bucket
    ));
    // Request succeeded
    if (isset($result['Contents'])) {
        foreach ($result['Contents'] as $rt) {
            // print the object's key
            echo "Key: " . $rt['Key'] . "\\n";
            // print the object's ETag
            echo "ETag: " . $rt['ETag'] . "\\n";
            // print the object's size
            echo "Size: " . $rt['Size'] . "\\n";
            echo "---\\n";
        }
    }
} catch (\\Exception $e) {
    //Request failed
    echo($e);
}

Running Environment

Operating System: Ubuntu 24.04.3 LTS / x86_64
Runtime Version: PHP 8.3.6 (cli) (built: Jul 14 2025 18:30:55) (NTS)
A single call to the listObjects API can query up to 1000 objects. To query all objects, you need to make repeated calls.
require dirname(__FILE__) . '/../vendor/autoload.php';

$secretId = getenv('COS_SECRET_ID'); // User's SecretId. It is recommended to use a sub-account key; authorization follows the principle of least privilege to reduce usage risks. For obtaining sub-account keys, refer to https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$secretKey = getenv('COS_SECRET_KEY'); // User's SecretKey. It is recommended to use a sub-account key; authorization follows the principle of least privilege to reduce usage risks. For obtaining sub-account keys, refer to https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$region = getenv('COS_REGION'); // Your region. The region of the created bucket can be viewed in the console: https://console.tencentcloud.com/cos5/bucket
$cosClient = new Qcloud\\Cos\\Client(
    array(
        'region' => $region,
        'scheme' => 'https', // Protocol header, which defaults to http
        'credentials'=> array(
            'secretId'  => $secretId,
            'secretKey' => $secretKey)));

// To obtain more objects than the maxkeys limit or to obtain all objects, you need to call listObjects repeatedly.
// Use the NextMarker returned last time as the Marker for the next call until the returned IsTruncated is false.
try {
    $bucket = "examplebucket-1250000000"; // Bucket name format: BucketName-APPID.
    $prefix = ''; // Prefix of the list object
    $marker = ''; // The breakpoint where the object was last listed
    while (true) {
        $result = $cosClient->listObjects(array(
            'Bucket' => $bucket,
            'Marker' => $marker,
            'MaxKeys' => 1000 // Set the maximum quantities of prints in a single query to 1,000.
        ));
        if (isset($result['Contents'])) {
            foreach ($result['Contents'] as $rt) {
                // print key
                echo($rt['Key'] . "\\n");
            }
        }
        $marker = $result['NextMarker']; // Set a new breakpoint.
        if (!$result['IsTruncated']) {
            break; // Judge whether the query has been completed or not.
        }
    }
} catch (\\Exception $e) {
    echo($e);
}

After uploading an object, you can use the same key to call the GetObject API to download the object locally. You can also generate a pre-signed URL (for downloading, specify the method as GET; for details, see Pre-signed URL) and share it with other endpoints for download. However, if your file is set with private read permissions, note the validity period of the pre-signed URL.
Download the file to the specified local path. For the complete sample on downloading objects, go to GitHub.
require dirname(__FILE__) . '/../vendor/autoload.php';

$secretId = getenv('COS_SECRET_ID'); // User's SecretId. It is recommended to use a sub-account key; authorization follows the principle of least privilege to reduce usage risks. For obtaining sub-account keys, refer to https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$secretKey = getenv('COS_SECRET_KEY'); // User's SecretKey. It is recommended to use a sub-account key; authorization follows the principle of least privilege to reduce usage risks. For obtaining sub-account keys, refer to https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$region = getenv('COS_REGION'); // Your region. The region of the created bucket can be viewed in the console: https://console.tencentcloud.com/cos5/bucket
$cosClient = new Qcloud\\Cos\\Client(
    array(
        'region' => $region,
        'scheme' => 'https', // Protocol header, which defaults to http
        'credentials'=> array(
            'secretId'  => $secretId,
            'secretKey' => $secretKey)));

# Download files.
## getObject (Download files).
### Download files to the memory.
try {
    $bucket = "examplebucket-1250000000"; //bucket, format: BucketName-APPID
    $key = "exampleobject"; // Here, key is the object key, which is the unique identifier of an object in the bucket.
    $result = $cosClient->getObject(array(
        'Bucket' => $bucket,
        'Key' => $key));
    // Request succeeded
    echo($result['Body']);
} catch (\\Exception $e) {
    //Request failed
    echo "$e\\n";
}

### Download files to a local directory.
try {
    $bucket = "examplebucket-1250000000"; //bucket, format: BucketName-APPID
    $key = "exampleobject"; // Here, key is the object key, which is the unique identifier of an object in the bucket.
    $localPath = @"path/to/localFile"; // Download to the specified local path.
    $result = $cosClient->getObject(array(
        'Bucket' => $bucket,
        'Key' => $key,
        'SaveAs' => $localPath));
} catch (\\Exception $e) {
    //Request failed
    echo "$e\\n";
}

### Specify the download range.
/*
 * The format of the Range field is 'bytes=ab'.
 */
try {
    $bucket = "examplebucket-1250000000"; //bucket, format: BucketName-APPID
    $key = "exampleobject"; // Here, key is the object key, which is the unique identifier of an object in the bucket.
    $localPath = @"path/to/localFile"; // Download to the specified local path.
    $result = $cosClient->getObject(array(
        'Bucket' => $bucket,
        'Key' => $key,
        'Range' => 'bytes=0-10',
        'SaveAs' => $localPath));
} catch (\\Exception $e) {
    //Request failed
    echo "$e\\n";
}

## getObjectUrl (Obtain the file UrL).
try {    
    $bucket = "examplebucket-1250000000"; //bucket, format: BucketName-APPID
    $key = "exampleobject"; // Here, key is the object key, which is the unique identifier of an object in the bucket.
    $signedUrl = $cosClient->getObjectUrl($bucket, $key, '+10 minutes');
    // Request succeeded
    echo $signedUrl;
} catch (\\Exception $e) {
    //Request failed
    print_r($e);
}
Note:
After an object is deleted, its corresponding data can no longer be accessed.
To delete an object at a specified path in COS, refer to the following example code. For the complete sample on object deletion, go to GitHub.
# Delete object
## deleteObject
try {
    $bucket = "examplebucket-1250000000"; //bucket, format: BucketName-APPID
    $key = "exampleobject"; // Here, key is the object key, which is the unique identifier of an object in the bucket.
    $result = $cosClient->deleteObject(array(
        'Bucket' => $bucket,
        'Key' => $key,
        'VersionId' => 'string'
    ));
    // Request succeeded
    print_r($result);
} catch (\\Exception $e) {
    //Request failed
    echo($e);
}
# Delete multiple objects
## deleteObjects
try {
    $bucket = "examplebucket-1250000000"; //bucket, format: BucketName-APPID
    $key1 = "exampleobject1"; // Here, key is the object key, which is the unique identifier of an object in the bucket.
    $key2 = "exampleobject2"; // Here, key is the object key, which is the unique identifier of an object in the bucket.
    $result = $cosClient->deleteObjects(array(
        'Bucket' => $bucket,
        'Objects' => array(
            array(
                'Key' => $key1,
            ),
            array(
                'Key' => $key2,
            ),
            //...
        ),
    ));
    // Request succeeded
    print_r($result);
} catch (\\Exception $e) {
    //Request failed
    echo($e);
}

FAQs

For common issues you may encounter during use, refer to PHP SDK FAQ for related solutions.

次の記事へ: 製品アップデート情報

ヘルプとサポート

この記事はお役に立ちましたか？

フィードバック