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.1(1mo ago)44672.8k↓12.7%95MITPHPPHP >=8.0.2CI passing Since Oct 30Pushed 1mo 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 4d ago READMEChangelog (10)Dependencies (18)Versions (26)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 62 — FairBetter than 99% of packages Maintenance91 Actively maintained with recent releases Popularity50 Moderate usage in the ecosystem Community25 Small or concentrated contributor base Maturity69 Established project with proven stability Bus Factor1 Top contributor holds 90.6% 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 ~88 days Recently: every ~99 days Total 24 Last Release 44d 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 (77 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 [aws/aws-sdk-php AWS SDK for PHP - Use Amazon Web Services in your PHP project 6.3k543.5M2.6k](/packages/aws-aws-sdk-php)[neuron-core/neuron-ai The PHP Agentic Framework. 2.0k656.1k38](/packages/neuron-core-neuron-ai)[guzzlehttp/psr7 PSR-7 message implementation that also provides common utility methods 8.0k1.1B4.0k](/packages/guzzlehttp-psr7)[tempest/framework The PHP framework that gets out of your way. 2.2k34.4k15](/packages/tempest-framework)[spatie/laravel-export Create a static site bundle from a Laravel app 674146.0k6](/packages/spatie-laravel-export)[oat-sa/tao-core TAO core extension 66143.7k124](/packages/oat-sa-tao-core) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)