PHPackages overtrue/qcloud-cos-client - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [HTTP & Networking](/categories/http) 4. / 5. overtrue/qcloud-cos-client ActiveLibrary[HTTP & Networking](/categories/http) overtrue/qcloud-cos-client ========================== Client of QCloud.com COS 2.2.0(1y ago)43637.0k—0.7%95MITPHPPHP >=8.0.2CI passing Since Oct 30Pushed 5mo ago4 watchersCompare [ Source](https://github.com/overtrue/qcloud-cos-client)[ Packagist](https://packagist.org/packages/overtrue/qcloud-cos-client)[ GitHub Sponsors](https://github.com/overtrue)[ RSS](/packages/overtrue-qcloud-cos-client/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (10)Dependencies (9)Versions (24)Used By (5) [![](https://github.com/overtrue/qcloud-cos-client/workflows/Test/badge.svg)](https://github.com/overtrue/qcloud-cos-client/workflows/Test/badge.svg) QCloud COS Client ================= [](#qcloud-cos-client) 对象存储（Cloud Object Storage，COS）是腾讯云提供的一种存储海量文件的分布式存储服务，具有高扩展性、低成本、可靠安全等优点。通过控制台、API、SDK 和工具等多样化方式，用户可简单、快速地接入 COS，进行多格式文件的上传、下载和管理，实现海量数据存储和管理。 > ⭐ 官方文档： [![Sponsor me](https://github.com/overtrue/overtrue/raw/master/sponsor-me-button-s.svg?raw=true)](https://github.com/sponsors/overtrue) 安装 -- [](#安装) 环境要求： - PHP >= 8.0 - ext-libxml - ext-simplexml - ext-json - ext-dom ``` $ composer require overtrue/qcloud-cos-client -vvv ``` 配置 -- [](#配置) 配置前请了解官方名词解释：[文档中心 > 对象存储 > API 文档 > 简介：术语信息](https://cloud.tencent.com/document/product/436/7751#.E6.9C.AF.E8.AF.AD.E4.BF.A1.E6.81.AF) ``` $config = [ // 必填，app_id、secret_id、secret_key // 可在个人秘钥管理页查看：https://console.cloud.tencent.com/capi 'app_id' => 10020201024, 'secret_id' => 'AKIDsiQzQla780mQxLLU2GJCxxxxxxxxxxx', 'secret_key' => 'b0GMH2c2NXWKxPhy77xhHgwxxxxxxxxxxx', // 可选(批量处理接口必填)，腾讯云账号 ID // 可在腾讯云控制台账号信息中查看：https://console.cloud.tencent.com/developer 'uin' => '10000*******', // 可选，地域列表请查看 https://cloud.tencent.com/document/product/436/6224 'region' => 'ap-guangzhou', // 可选，仅在调用不同的接口时按场景必填 'bucket' => 'example', // 使用 Bucket 接口时必填 // 可选，签名有效期，默认 60 分钟 'signature_expires' => '+60 minutes', // 可选，guzzle 配置 // 参考：https://docs.guzzlephp.org/en/7.0/request-options.html 'guzzle' => [ // ... ], ]; ``` 使用 -- [](#使用) 您可以分两种方式使用此 SDK： - **ServiceClient、BucketClient、ObjectClient、JobClient** - 封装了具体 API 的类调用指定业务的 API。 - **Client** - 基于最基础的 HTTP 类封装调用 COS 全部 API。 在使用前我们强烈建议您仔细阅读[官方 API 文档](https://cloud.tencent.com/document/product/436)，以减少不必要的时间浪费。 ### 返回值 [](#返回值) 所有的接口调用都会返回 [`Overtrue\CosClient\Http\Response`](https://github.com/overtrue/qcloud-cos-client/blob/master/src/Http/Response.php) 对象，该对象提供了以下便捷方法： ``` array|null $response->toArray(); // 获取响应内容数组转换结果 object $response->toObject(); // 获取对象格式的返回值 bool $response->isXML(); // 检测返回内容是否为 XML string $response->getContents(); // 获取原始返回内容 ``` 你也可以直接把 `$response` 当成数组访问：`$response['ListBucketResult']` ServiceClient ------------- [](#serviceclient) ``` use Overtrue\CosClient\ServiceClient; $config = [ // 请参考配置说明 ]; $service = new ServiceClient($config); $service->getBuckets(); $service->getBuckets('ap-guangzhou'); ``` JobClient --------- [](#jobclient) ``` use Overtrue\CosClient\JobClient; $config = [ // 请参考配置说明 ]; $job = new JobClient($config); ## API $job->getJobs(array $query = []); $job->createJob(array $body); $job->describeJob(string $id); $job->updateJobPriority(string $id, int $priority); $job->updateJobStatus(string $id, array $query); ``` BucketClient ------------ [](#bucketclient) ``` use Overtrue\CosClient\BucketClient; $config = [ // 请参考配置说明 'bucket' => 'example', 'region' => 'ap-guangzhou', ]; $bucket = new BucketClient($config); ## API $bucket->putBucket(array $body); $bucket->headBucket(); $bucket->deleteBucket(); $bucket->getObjects(array $query = []); $bucket->getObjectVersions(array $query = []); // Versions $bucket->putVersions(array $body); $bucket->getVersions(); // ACL $bucket->putACL(array $body, array $headers = []) $bucket->getACL(); // CORS $bucket->putCORS(array $body); $bucket->getCORS(); $bucket->deleteCORS(); // Lifecycle $bucket->putLifecycle(array $body); $bucket->getLifecycle(); $bucket->deleteLifecycle(); // Policy $bucket->putPolicy(array $body); $bucket->getPolicy(); $bucket->deletePolicy(); // Referer $bucket->putReferer(array $body); $bucket->getReferer(); // Taging $bucket->putTaging(array $body); $bucket->getTaging(); $bucket->deleteTaging(); // Website $bucket->putWebsite(array $body); $bucket->getWebsite(); $bucket->deleteWebsite(); // Inventory $bucket->putInventory(string $id, array $body) $bucket->getInventory(string $id) $bucket->getInventoryConfigurations(?string $nextContinuationToken = null) $bucket->deleteInventory(string $id) // Versioning $bucket->putVersioning(array $body); $bucket->getVersioning(); // Replication $bucket->putReplication(array $body); $bucket->getReplication(); $bucket->deleteReplication(); // Logging $bucket->putLogging(array $body); $bucket->getLogging(); // Accelerate $bucket->putAccelerate(array $body); $bucket->getAccelerate(); // Encryption $bucket->putEncryption(array $body); $bucket->getEncryption(); $bucket->deleteEncryption(); ``` ObjectClient ------------ [](#objectclient) ``` use Overtrue\CosClient\ObjectClient; $config = [ // 请参考配置说明 'bucket' => 'example', 'region' => 'ap-guangzhou', ]); $object = new ObjectClient($config); $object->putObject(string $key, string $body, array $headers = []); $object->copyObject(string $key, array $headers = []); $object->getObject(string $key, array $query = [], array $headers = []); $object->headObject(string $key, string $versionId, array $headers = []); $object->restoreObject(string $key, string $versionId, array $body); $object->selectObjectContents(string $key, array $body); $object->deleteObject(string $key, string $versionId); $object->deleteObjects(array $body); $object->putObjectACL(string $key, array $body, array $headers = []); $object->getObjectACL(string $key); $object->putObjectTagging(string $key, string $versionId, array $body); $object->getObjectTagging(string $key, string $versionId); $object->deleteObjectTagging(string $key, string $versionId); $object->createUploadId(string $key, array $headers = []); $object->putPart(string $key, int $partNumber, string $uploadId, string $body, array $headers = []); $object->copyPart(string $key, int $partNumber, string $uploadId, array $headers = []); $object->markUploadAsCompleted(string $key, string $uploadId, array $body); $object->markUploadAsAborted(string $key, string $uploadId); $object->getUploadJobs(array $query = []); $object->getUploadedParts(string $key, string $uploadId, array $query = []); $object->getObjectUrl(string $key) $object->getObjectSignedUrl(string $key, string $expires = '+60 minutes') ``` 异常处理 ---- [](#异常处理) ``` use Overtrue\CosClient\BucketClient; $client = new BucketClient([ 'app_id' => 123456789, 'secret_id' => 'AKIDsiQzQla780mQxLLUxxxxxxx', 'secret_key' => 'b0GMH2c2NXWKxPhy77xxxxxxxx', 'region' => 'ap-guangzhou', 'bucket' => 'example', ]); try { $client->getObjects(); } catch(\Throwable $e) { var_dump($e->getResponse()->toArray()); } ``` 其中 `$e->getResponse()` 为 `\Overtrue\CosClient\Http\Response` 示例，你也可以通过 `$e->getRequest()` 获取请求对象。 测试 -- [](#测试) 你可以使用类提供的 `spy` 方法来创建一个测试对象： ``` use Overtrue\CosClient\Http\Response; use Overtrue\CosClient\ServiceClient; $service = ServiceClient::spy(); $mockResponse = Response::create(200, [], ' examplebucket1-1250000000 ap-beijing 2019-05-24T11:49:50Z '); $service->shouldReceive('listBuckets') ->with('zp-guangzhou') ->once() ->andReturn($mockResponse); ``` 更多测试写法请阅读：[Mockery 官方文档](http://docs.mockery.io/en/latest/index.html) ❤️ Sponsor me ------------- [](#heart-sponsor-me) [![Sponsor me](https://github.com/overtrue/overtrue/raw/master/sponsor-me.svg?raw=true)](https://github.com/sponsors/overtrue) 如果你喜欢我的项目并想支持它，[点击这里 ❤️](https://github.com/sponsors/overtrue) Project supported by JetBrains ------------------------------ [](#project-supported-by-jetbrains) Many thanks to Jetbrains for kindly providing a license for me to work on this and other open-source projects. [![](https://camo.githubusercontent.com/3cf726e7cdadba47755b7f7ea4227945a92a2fa48aadf4a2573140ec6501c989/68747470733a2f2f7265736f75726365732e6a6574627261696e732e636f6d2f73746f726167652f70726f64756374732f636f6d70616e792f6272616e642f6c6f676f732f6a625f6265616d2e737667)](https://www.jetbrains.com/?from=https://github.com/overtrue) Contributing ------------ [](#contributing) You can contribute in one of three ways: 1. File bug reports using the [issue tracker](https://github.com/vendor/package/issues). 2. Answer questions or fix bugs on the [issue tracker](https://github.com/vendor/package/issues). 3. Contribute new features or update the wiki. *The code contribution process is not very formal. You just need to make sure that you follow the PSR-0, PSR-1, and PSR-2 coding guidelines. Any new code contributions must be accompanied by unit tests where applicable.* License ------- [](#license) MIT ### Health Score 54 — FairBetter than 97% of packages Maintenance60 Regular maintenance activity Popularity49 Moderate usage in the ecosystem Community25 Small or concentrated contributor base Maturity68 Established project with proven stability Bus Factor1 Top contributor holds 90.1% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~75 days Recently: every ~6 days Total 23 Last Release 368d ago Major Versions 1.0.2 → 2.0.02022-04-24 1.0.4 → 2.0.12023-06-27 1.0.7 → 2.1.82025-04-21 1.x-dev → 2.1.102025-05-11 PHP version history (2 changes)1.0.0PHP >=7.4 2.0.0PHP >=8.0.2 ### Community Maintainers ![](https://www.gravatar.com/avatar/c507e57eab402e81335012357b7d7df6c5cafda3073adcc94b475037127d263f?d=identicon)[overtrue](/maintainers/overtrue) --- Top Contributors [![overtrue](https://avatars.githubusercontent.com/u/1472352?v=4)](https://github.com/overtrue "overtrue (73 commits)")[![big-dream](https://avatars.githubusercontent.com/u/9215157?v=4)](https://github.com/big-dream "big-dream (2 commits)")[![thisliu](https://avatars.githubusercontent.com/u/29086766?v=4)](https://github.com/thisliu "thisliu (2 commits)")[![OneHundred86](https://avatars.githubusercontent.com/u/22148561?v=4)](https://github.com/OneHundred86 "OneHundred86 (1 commits)")[![mouyong](https://avatars.githubusercontent.com/u/10336437?v=4)](https://github.com/mouyong "mouyong (1 commits)")[![JieAnthony](https://avatars.githubusercontent.com/u/38497992?v=4)](https://github.com/JieAnthony "JieAnthony (1 commits)")[![lonquan](https://avatars.githubusercontent.com/u/12944913?v=4)](https://github.com/lonquan "lonquan (1 commits)") --- Tags cos-sdkqcloud-cosqcloud-sdktencent-cloudtencent-cos ### Code Quality TestsPHPUnit Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/overtrue-qcloud-cos-client/health.svg) ``` [![Health](https://phpackages.com/badges/overtrue-qcloud-cos-client/health.svg)](https://phpackages.com/packages/overtrue-qcloud-cos-client) ``` ### Alternatives [shopify/shopify-api Shopify API Library for PHP 4634.8M16](/packages/shopify-shopify-api)[neuron-core/neuron-ai The PHP Agentic Framework. 1.8k245.3k21](/packages/neuron-core-neuron-ai)[phpro/http-tools HTTP tools for developing more consistent HTTP implementations. 28137.8k](/packages/phpro-http-tools)[huaweicloud/huaweicloud-sdk-php Huawei Cloud SDK for PHP 1829.2k2](/packages/huaweicloud-huaweicloud-sdk-php)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 245.2k](/packages/aedart-athenaeum) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)