tencent cloud

对象存储

文档对象存储SDK 文档PHP SDK快速入门

快速入门

下载
聚焦模式
字号
最后更新时间： 2026-06-18 10:46:31

相关资源

对象存储 COS 的 XML PHP SDK 源码下载地址：XML PHP SDK。
SDK 快速下载地址：XML PHP SDK。
示例 Demo 程序地址：PHP sample。
SDK 文档中的所有示例代码请参见 SDK 代码示例。
SDK 更新日志请参见 CHANGELOG。
SDK 常见问题请参见：PHP SDK 常见问题。

环境配置与准备

版本说明：PHP 5.6及以上。
注意：
您可以通过 php -v 命令查看当前的 PHP 版本。
如果您的 PHP 版本为5.3及以上且5.6以下，请使用 v1.3 版本。
所需扩展包：cURL 扩展、xml 扩展、dom 扩展、mbstring 扩展、json 扩展。
说明：
您可以通过 php -m 命令查看以上扩展是否已经安装好。
不同系统中安装扩展的命令示例如下：
Ubuntu 系统中，您可以使用 apt-get 包管理器安装 PHP 的相关扩展，安装命令如下。
sudo apt-get install php-curl php-xml php-dom php-mbstring php-json
CentOS 系统中，您可以使用 yum 包管理器安装 PHP 的 cURL 扩展。
sudo yum install php-curl php-xml php-dom php-mbstring php-json

安装 SDK

SDK 安装有三种方式：Composer 方式、Phar 方式和源码方式。
Composer 方式
Phar 方式
源码方式
推荐使用 Composer 安装 cos-php-sdk-v5，Composer 是 PHP 的依赖管理工具，允许您声明项目所需的依赖，然后自动将它们安装到您的项目中。
说明：
您可以在 Composer 官网 上找到更多关于如何安装 Composer，配置自动加载以及用于定义依赖项的其他最佳实践等相关信息。
1. 打开终端。
2. 执行以下命令，下载 Composer。
curl -sS https://getcomposer.org/installer | php
3. 创建一个名为 composer.json 的文件，内容如下。
{
 "require": {
     "qcloud/cos-sdk-v5": ">=2.0"
 }
}
4. 执行以下命令，使用 Composer 安装。
php composer.phar install
使用该命令后会在当前目录中创建一个 vendor 文件夹，里面包含 SDK 的依赖库和一个 autoload.php 脚本，方便在项目中调用。
注意：
目前已支持 Composer 根据当前 PHP 版本下载 Guzzle6 或 Guzzle7。Guzzle7 版本支持 laravel8 框架。当 PHP 版本为7.2.5及以上时自动下载 Guzzle7 版本，反之下载 Guzzle6 版本。
5. 通过 autoloader 脚本调用 cos-php-sdk-v5，在代码中引入 autoload.php 文件。
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)
注意：
执行 composer 安装后，这里的路径需更改为 autoload.php 文件所对应的路径，否则会调用不到相关方法。如您安装的路径为/Users/username/project，则项目中引用的路径应填写为/Users/username/project/vendor/autoload.php。
至此，您的项目已经可以使用 COS XML PHP SDK 了。
1. 在 GitHub 发布页面 下载相应的 phar 文件。
说明：
当 PHP 版本为5.6及以上且7.2.5以下时，请下载 cos-sdk-v5-6.phar，使用 Guzzle6 版本。
当 PHP 版本为7.2.5及以上时，请下载 cos-sdk-v5-7.phar，使用 Guzzle7 版本。
2. 在代码中引入 phar 文件。
require '/path/to/cos-sdk-v5-x.phar';
1. 在 SDK 下载页面 下载 cos-sdk-v5.tar.gz 压缩文件。
说明：
当 PHP 版本为5.6及以上且7.2.5以下时，请下载 cos-sdk-v5-6.tar.gz，使用 Guzzle6 版本。
当 PHP 版本为7.2.5及以上时，请下载 cos-sdk-v5-7.tar.gz，使用 Guzzle7 版本。
2. 解压后通过 autoload.php 脚本加载 SDK，在代码中引入 autoload.php 文件。
require '/path/to/sdk/vendor/autoload.php';
注意：
Source code 压缩包为 GitHub 默认打包的代码包，里面不包含 vendor 目录。请注意下载 release 包（cos-sdk-v5-x.tar.gz 包）而不是 Source 包，也不要直接 clone 整个仓库。否则会缺失 index.php 以及 vendor 包。

初始化 COS 服务

下面为您介绍如何使用 COS PHP SDK 完成初始化客户端、创建存储桶、查询存储桶列表、上传对象、查询对象列表、下载对象和删除对象。关于示例中的参数说明，请参见 存储桶操作 和 对象操作 文档。

初始化 COS

注意：
建议用户使用子账号密钥 + 环境变量的方式调用 SDK，提高 SDK 使用的安全性。为子账号授权时，请遵循 最小权限指引原则，防止泄露目标存储桶或对象之外的资源。
如果您一定要使用永久密钥，建议遵循 最小权限指引原则 对永久密钥的权限范围进行限制。
临时密钥
永久密钥
若您使用 临时密钥 初始化，请使用以下方式创建实例。
$tmpSecretId = "TmpSecretId"; //临时密钥的 SecretId，临时密钥生成和使用指引参见 https://www.tencentcloud.com/document/product/436/14048
$tmpSecretKey = "TmpSecretKey"; //临时密钥的 SecretKey，临时密钥生成和使用指引参见 https://www.tencentcloud.com/document/product/436/14048
$tmpToken = "TmpToken"; //临时密钥的 Token，临时密钥生成和使用指引参见 https://www.tencentcloud.com/document/product/436/14048
$region = "ap-beijing"; //替换为用户的 region，已创建桶归属的 region 可以在控制台查看，https://console.tencentcloud.com/cos5/bucket
$cosClient = new Qcloud\\Cos\\Client(
    array(
        'region' => $region,
        'scheme' => 'https', //协议头部，默认为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)
若您使用永久密钥初始化 COSClient，可以先在访问管理控制台中的 API 密钥管理页面 获取 SecretId、SecretKey，使用永久密钥适用于大部分的应用场景。
// SECRETID 和 SECRETKEY 请登录访问管理控制台进行查看和管理
$secretId = getenv('COS_SECRET_ID'); //用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$secretKey = getenv('COS_SECRET_KEY'); //用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$region = "ap-beijing"; //用户的 region，已创建桶归属的 region 可以在控制台查看，https://console.tencentcloud.com/cos5/bucket
$cosClient = new Qcloud\\Cos\\Client(
    array(
        'region' => $region,
        'scheme' => 'https', //协议头部，默认为 http
        'credentials'=> array(
            'secretId'  => $secretId ,
            'secretKey' => $secretKey)));
注意：
若未配置 HTTPS 证书，则需要删除 scheme 参数或填入 'scheme' => 'http'；若填入 https 会出现 certificate problem。若您需要配置证书，可参见 PHP SDK 常见问题。

访问 COS 服务

创建存储桶
查询存储桶列表
上传对象
查询对象列表
下载对象
删除对象
用户确定地域和存储桶名称后，参考如下示例创建存储桶。关于创建存储桶的完整示例，请前往 GitHub 查看。
require dirname(__FILE__) . '/../vendor/autoload.php';

$secretId = getenv('COS_SECRET_ID'); //用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$secretKey = getenv('COS_SECRET_KEY'); //用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$region = getenv('COS_REGION'); //用户的 region，已创建桶归属的 region 可以在控制台查看，https://console.tencentcloud.com/cos5/bucket
$cosClient = new Qcloud\\Cos\\Client(
    array(
        'region' => $region,
        'scheme' => 'https', //协议头部，默认为 http
        'credentials'=> array(
            'secretId'  => $secretId,
            'secretKey' => $secretKey)));

try {
    $bucket = "examplebucket-1250000000"; //存储桶名称 格式：BucketName-APPID
    $result = $cosClient->createBucket(array('Bucket' => $bucket));
    //请求成功
    print_r($result);
} catch (\\Exception $e) {
    //请求失败
    echo($e);
}
查询用户的存储桶列表，参考如下示例。关于查询存储桶列表的完整示例，请前往 GitHub 查看。
require dirname(__FILE__) . '/../vendor/autoload.php';

$secretId = getenv('COS_SECRET_ID'); //用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$secretKey = getenv('COS_SECRET_KEY'); //用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$region = getenv('COS_REGION'); //用户的 region，已创建桶归属的 region 可以在控制台查看，https://console.tencentcloud.com/cos5/bucket
$cosClient = new Qcloud\\Cos\\Client(
    array(
        'region' => $region,
        'scheme' => 'https', //协议头部，默认为 http
        'credentials'=> array(
            'secretId'  => $secretId,
            'secretKey' => $secretKey)));

try {
    //请求成功
    $result = $cosClient->listBuckets();
    // 打印存储桶列表信息
    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) {
    //请求失败
    echo($e);
}
关于上传对象的完整示例，请前往 GitHub 查看。
注意：
使用 putObject 接口上传文件（最大5G）。
使用 Upload 接口分块上传文件，Upload 接口为复合上传接口，对小文件进行简单上传，对大文件进行分块上传。
参数说明可参见 上传对象 文档。
require dirname(__FILE__) . '/../vendor/autoload.php';

$secretId = getenv('COS_SECRET_ID'); //用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$secretKey = getenv('COS_SECRET_KEY'); //用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$region = getenv('COS_REGION'); //用户的 region，已创建桶归属的 region 可以在控制台查看，https://console.tencentcloud.com/cos5/bucket
$cosClient = new Qcloud\\Cos\\Client(
    array(
        'region' => $region,
        'scheme' => 'https', //协议头部，默认为 http
        'credentials'=> array(
            'secretId'  => $secretId,
            'secretKey' => $secretKey)));

# 上传文件
## putObject(上传接口，最大支持上传5G文件)
### 上传内存中的字符串
try {
    $bucket = "examplebucket-1250000000"; //存储桶名称 格式：BucketName-APPID
    $key = "exampleobject"; //此处的 key 为对象键，对象键是对象在存储桶中的唯一标识
    $result = $cosClient->putObject(array(
        'Bucket' => $bucket,
        'Key' => $key,
        'Body' => 'Hello World!'));
    print_r($result);
} catch (\\Exception $e) {
    echo "$e\\n";
}

### 上传文件流
try {
    $bucket = "examplebucket-1250000000"; //存储桶名称 格式：BucketName-APPID
    $key = "exampleobject"; //此处的 key 为对象键，对象键是对象在存储桶中的唯一标识
    $srcPath = "path/to/localFile";//本地文件绝对路径
    $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(高级上传接口，默认使用分块上传最大支持50T)
### 上传内存中的字符串
try {    
    $bucket = "examplebucket-1250000000"; //存储桶名称 格式：BucketName-APPID
    $key = "exampleobject"; //此处的 key 为对象键，对象键是对象在存储桶中的唯一标识
    $result = $cosClient->Upload(
        $bucket = $bucket,
        $key = $key,
        $body = 'Hello World!');
    print_r($result);
} catch (\\Exception $e) {
    echo "$e\\n";
}

### 上传文件流
try {    
    $bucket = "examplebucket-1250000000"; //存储桶名称 格式：BucketName-APPID
    $key = "exampleobject"; //此处的 key 为对象键，对象键是对象在存储桶中的唯一标识
    $srcPath = "path/to/localFile";//本地文件绝对路径
    $file = fopen($srcPath, 'rb');
    if ($file) {
        $result = $cosClient->Upload(
            $bucket = $bucket,
            $key = $key,
            $body = $file);
    }
    print_r($result);
} catch (\\Exception $e) {
    echo "$e\\n";
}
查询存储桶中对象列表，参考如下示例。关于查询对象列表的完整示例，请前往 GitHub 查看。
require dirname(__FILE__) . '/../vendor/autoload.php';

$secretId = getenv('COS_SECRET_ID'); //用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$secretKey = getenv('COS_SECRET_KEY'); //用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$region = getenv('COS_REGION'); //用户的 region，已创建桶归属的 region 可以在控制台查看，https://console.tencentcloud.com/cos5/bucket
$cosClient = new Qcloud\\Cos\\Client(
    array(
        'region' => $region,
        'scheme' => 'https', //协议头部，默认为 http
        'credentials'=> array(
            'secretId'  => $secretId,
            'secretKey' => $secretKey)));

try {
    $bucket = "examplebucket-1250000000"; //存储桶名称 格式：BucketName-APPID
    $result = $cosClient->listObjects(array(
        'Bucket' => $bucket
    ));
    // 请求成功
    if (isset($result['Contents'])) {
        foreach ($result['Contents'] as $rt) {
            // 打印对象的 key
            echo "Key: " . $rt['Key'] . "\\n";
            // 打印对象的 ETag
            echo "ETag: " . $rt['ETag'] . "\\n";
            // 打印对象的大小
            echo "Size: " . $rt['Size'] . "\\n";
            echo "---\\n";
        }
    }
} catch (\\Exception $e) {
    // 请求失败
    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)
单次调用 listObjects 接口只能查询1000个对象，如需要查询所有的对象，则需要循环调用。
require dirname(__FILE__) . '/../vendor/autoload.php';

$secretId = getenv('COS_SECRET_ID'); //用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$secretKey = getenv('COS_SECRET_KEY'); //用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$region = getenv('COS_REGION'); //用户的 region，已创建桶归属的 region 可以在控制台查看，https://console.tencentcloud.com/cos5/bucket
$cosClient = new Qcloud\\Cos\\Client(
    array(
        'region' => $region,
        'scheme' => 'https', //协议头部，默认为 http
        'credentials'=> array(
            'secretId'  => $secretId,
            'secretKey' => $secretKey)));

// 如果要获取超过 maxkeys 数量的 object 或者获取所有的 object，则需要循环调用 listObjects，
// 用上一次返回的 NextMarker 作为下一次调用的 Marker，直到返回的 IsTruncated 为 false
try {
    $bucket = "examplebucket-1250000000"; //存储桶名称 格式：BucketName-APPID
    $prefix = ''; //列出对象的前缀
    $marker = ''; //上次列出对象的断点
    while (true) {
        $result = $cosClient->listObjects(array(
            'Bucket' => $bucket,
            'Marker' => $marker,
            'MaxKeys' => 1000 //设置单次查询打印的最大数量，最大为1000
        ));
        if (isset($result['Contents'])) {
            foreach ($result['Contents'] as $rt) {
                // 打印key
                echo($rt['Key'] . "\\n");
            }
        }
        $marker = $result['NextMarker']; //设置新的断点
        if (!$result['IsTruncated']) {
            break; //判断是否已经查询完
        }
    }
} catch (\\Exception $e) {
    echo($e);
}

上传对象后，您可以用同样的 key，调用 GetObject 接口将对象下载到本地，也可以生成预签名链接（下载请指定 method 为 GET，详情请参见 预签名 URL），分享到其他终端来进行下载。但如果您的文件设置了私有读权限，那么请注意预签名链接的有效期。
将文件下载到本地指定路径，参考如下示例。关于下载对象的完整示例，请前往 GitHub 查看。
require dirname(__FILE__) . '/../vendor/autoload.php';

$secretId = getenv('COS_SECRET_ID'); //用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$secretKey = getenv('COS_SECRET_KEY'); //用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
$region = getenv('COS_REGION'); //用户的 region，已创建桶归属的 region 可以在控制台查看，https://console.tencentcloud.com/cos5/bucket
$cosClient = new Qcloud\\Cos\\Client(
    array(
        'region' => $region,
        'scheme' => 'https', //协议头部，默认为 http
        'credentials'=> array(
            'secretId'  => $secretId,
            'secretKey' => $secretKey)));

# 下载文件
## getObject(下载文件)
### 下载到内存
try {
    $bucket = "examplebucket-1250000000"; //存储桶，格式：BucketName-APPID
    $key = "exampleobject";  //此处的 key 为对象键，对象键是对象在存储桶中的唯一标识
    $result = $cosClient->getObject(array(
        'Bucket' => $bucket,
        'Key' => $key));
    // 请求成功
    echo($result['Body']);
} catch (\\Exception $e) {
    // 请求失败
    echo "$e\\n";
}

### 下载到本地
try {
    $bucket = "examplebucket-1250000000"; //存储桶，格式：BucketName-APPID
    $key = "exampleobject";  //此处的 key 为对象键，对象键是对象在存储桶中的唯一标识
    $localPath = @"path/to/localFile";//下载到本地指定路径
    $result = $cosClient->getObject(array(
        'Bucket' => $bucket,
        'Key' => $key,
        'SaveAs' => $localPath));
} catch (\\Exception $e) {
    // 请求失败
    echo "$e\\n";
}

### 指定下载范围
/*
 * Range 字段格式为 'bytes=a-b'
 */
try {
    $bucket = "examplebucket-1250000000"; //存储桶，格式：BucketName-APPID
    $key = "exampleobject";  //此处的 key 为对象键，对象键是对象在存储桶中的唯一标识
    $localPath = @"path/to/localFile";//下载到本地指定路径
    $result = $cosClient->getObject(array(
        'Bucket' => $bucket,
        'Key' => $key,
        'Range' => 'bytes=0-10',
        'SaveAs' => $localPath));
} catch (\\Exception $e) {
    // 请求失败
    echo "$e\\n";
}

## getObjectUrl(获取文件 UrL)
try {    
    $bucket = "examplebucket-1250000000"; //存储桶，格式：BucketName-APPID
    $key = "exampleobject";  //此处的 key 为对象键，对象键是对象在存储桶中的唯一标识
    $signedUrl = $cosClient->getObjectUrl($bucket, $key, '+10 minutes');
    // 请求成功
    echo $signedUrl;
} catch (\\Exception $e) {
    // 请求失败
    print_r($e);
}
注意：
对象被删除后，其对应的数据将无法再被访问。
删除 COS 上指定路径的对象，参考如下示例代码。关于删除对象的完整示例，请前往 GitHub 查看。
# 删除 object
## deleteObject
try {
    $bucket = "examplebucket-1250000000"; //存储桶，格式：BucketName-APPID
    $key = "exampleobject";  //此处的 key 为对象键，对象键是对象在存储桶中的唯一标识
    $result = $cosClient->deleteObject(array(
        'Bucket' => $bucket,
        'Key' => $key,
        'VersionId' => 'string'
    ));
    // 请求成功
    print_r($result);
} catch (\\Exception $e) {
    // 请求失败
    echo($e);
}
# 删除多个 object
## deleteObjects
try {
    $bucket = "examplebucket-1250000000"; //存储桶，格式：BucketName-APPID
    $key1 = "exampleobject1";  //此处的 key 为对象键，对象键是对象在存储桶中的唯一标识
    $key2 = "exampleobject2";  //此处的 key 为对象键，对象键是对象在存储桶中的唯一标识
    $result = $cosClient->deleteObjects(array(
        'Bucket' => $bucket,
        'Objects' => array(
            array(
                'Key' => $key1,
            ),
            array(
                'Key' => $key2,
            ),
            //...
        ),
    ));
    // 请求成功
    print_r($result);
} catch (\\Exception $e) {
    // 请求失败
    echo($e);
}

常见问题

您在使用过程中可能会碰到的一些常见问题，相关的解决办法可参见 PHP SDK 常见问题。

上一篇: 异常处理下一篇: PHP SDK 常见问题

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈