PHPackages                             overtrue/laravel-qcloud-captcha - 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. [Utility & Helpers](/categories/utility)
4. /
5. overtrue/laravel-qcloud-captcha

ActiveLibrary[Utility & Helpers](/categories/utility)

overtrue/laravel-qcloud-captcha
===============================

腾讯云验证码服务

3.0.0(1y ago)814.4k↑185.6%1MITPHPCI failing

Since Nov 9Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/overtrue/laravel-qcloud-captcha)[ Packagist](https://packagist.org/packages/overtrue/laravel-qcloud-captcha)[ GitHub Sponsors](https://github.com/overtrue)[ RSS](/packages/overtrue-laravel-qcloud-captcha/feed)WikiDiscussions master Synced 3d ago

READMEChangelog (6)Dependencies (7)Versions (7)Used By (0)

Laravel Qcloud Captcha
----------------------

[](#laravel-qcloud-captcha)

[![CI](https://github.com/overtrue/laravel-qcloud-captcha/actions/workflows/ci.yml/badge.svg)](https://github.com/overtrue/laravel-qcloud-captcha/actions/workflows/ci.yml)[![Latest Stable Version](https://camo.githubusercontent.com/4591b17ace5099ca659980d88a22e54a20dcdec3814ea2d1bff4593ba0205680/68747470733a2f2f706f7365722e707567782e6f72672f6f766572747275652f6c61726176656c2d71636c6f75642d636170746368612f762f737461626c652e737667)](https://packagist.org/packages/overtrue/laravel-qcloud-captcha)[![Latest Unstable Version](https://camo.githubusercontent.com/c650b4d1baf2daeb19fdf46ec9e7ab15b244d67f2ceaba1646f9dc92d430b5d4/68747470733a2f2f706f7365722e707567782e6f72672f6f766572747275652f6c61726176656c2d71636c6f75642d636170746368612f762f756e737461626c652e737667)](https://packagist.org/packages/overtrue/laravel-qcloud-captcha)[![Total Downloads](https://camo.githubusercontent.com/4f4f405174a7c98e3a440db67e07d666a227122449663be833fba6fb1c370aff/68747470733a2f2f706f7365722e707567782e6f72672f6f766572747275652f6c61726176656c2d71636c6f75642d636170746368612f646f776e6c6f616473)](https://packagist.org/packages/overtrue/laravel-qcloud-captcha)[![License](https://camo.githubusercontent.com/0b74088bbb1f5e7701838fe23e62fc8f6ba1ad78262032f316c797e0dc6fbcbe/68747470733a2f2f706f7365722e707567782e6f72672f6f766572747275652f6c61726176656c2d71636c6f75642d636170746368612f6c6963656e7365)](https://packagist.org/packages/overtrue/laravel-qcloud-captcha)

腾讯云验证码是为网页、App 及小程序开发者提供的安全验证服务，目前网页及 App 支持以 Web 前端接入、App 端接入（iOS 和 Android）方式接入验证码服务，小程序开发者可以使用 小程序插件接入 方式接入验证码服务，基于腾讯多年的大数据积累和人工智能决策引擎，构建智能分级验证模型，最大程度保护业务安全的同时，提供更精细化的用户体验。

- 📖 [官方 API](https://cloud.tencent.com/document/product/1110/36334)

[![Sponsor me](https://github.com/overtrue/overtrue/raw/master/sponsor-me-button-s.svg?raw=true)](https://github.com/sponsors/overtrue)

Installing
----------

[](#installing)

```
$ composer require overtrue/laravel-qcloud-captcha -vvv
```

### Config

[](#config)

请在 `config/services.php` 中配置以下内容：

```
    //...
    // 验证码服务
    'captcha' => [
        // 腾讯云 API 秘钥：SecretId，SecretKey
        // https://console.cloud.tencent.com/cam/capi
        'secret_id' => env('CAPTCHA_SECRET_ID'),
        'secret_key' => env('CAPTCHA_SECRET_KEY'),

        // 验证码服务秘钥：CaptchaAppId，AppSecretKey
        'app_id' => env('CAPTCHA_APP_ID'),
        'app_secret_key' => env('CAPTCHA_APP_SECRET_KEY'),

        // 以下非必填
        'channel' =>  'web', // 渠道：web/miniapp，默认 web
        'endpoint' => env('CAPTCHA_ENDPOINT'), // 默认: captcha.tencentcloudapi.com
    ],
```

或者配置成多场景：

```
    //...
    // 验证码服务
    'captcha' => [
        // 默认 app 名称
        'default' => 'login',

        // app 配置
        'apps' => [
            'login' => [
                'secret_id' => env('CAPTCHA_LOGIN_SECRET_ID'),
                'secret_key' => env('CAPTCHA_LOGIN_SECRET_KEY'),
                'app_id' => env('CAPTCHA_LOGIN_APP_ID'),
                'app_secret_key' => env('CAPTCHA_LOGIN_APP_SECRET_KEY'),
            ],
            'register' => [
                'secret_id' => env('CAPTCHA_REGISTER_SECRET_ID'),
                'secret_key' => env('CAPTCHA_REGISTER_SECRET_KEY'),
                'app_id' => env('CAPTCHA_REGISTER_APP_ID'),
                'app_secret_key' => env('CAPTCHA_REGISTER_APP_SECRET_KEY'),
            ],
            //...
        ],
    ],
```

API
---

[](#api)

### 获取检查结果

[](#获取检查结果)

调用对应 API 返回 ticket 校验结果，返回值结构请参考官方 API 文档。

> 接口请求频率限制：1000次/秒。

```
use Overtrue\LaravelQcloudCaptcha\Captcha;

array Captcha::validate(string $ticket, ?string $app = null, ?string $nonce = null);
array Captcha::validateWebTicket(string $ticket, ?string $app = null, ?string $nonce = null);
array Captcha::validateMiniAppTicket(string $ticket, ?string $app = null);
```

验证失败将抛出以下异常：

- `Overtrue\LaravelQcloudCaptcha\InvalidTicketException`
    - `$ticket` - (string) 被检测的 ticket
    - `$response` - (array) API 原始返回值

使用表单校验规则
--------

[](#使用表单校验规则)

```
$this->validate($request, [
	'ticket' => 'required|captcha:randstr',
	'avatar' => 'required|url|ims',
	'description' => 'required|tms:strict',
	'logo_url' => 'required|url|ims:logo',
]);
```

**规则参数**：

**Web** 类型验证码校验时需要传入回调时的 **前端回调函数返回的随机字符串** 对应的表单名称，例如请求后端时使用 `randstr` 作为表单名称提交随机字符串：

```
// 请求内容
[
    'ticket' => 'xxxxxxxxx',
    'randstr' => 'xxxxxxxxx',
],

//1. 使用默认应用，并以请求中 `randstr` 作为随机字符串校验
'ticket' => 'required|captcha:randstr',

//2. 使用 `login` 应用，并以请求中 `randstr` 作为随机字符串校验
'ticket' => 'required|captcha:login,randstr',
```

**小程序** 验证码没有随机字符串参数：

```
// 请求内容
[
    'ticket' => 'xxxxxxxxx',
],

//1. 使用默认应用
'ticket' => 'required|captcha',

//2. 使用 `login` 应用
'ticket' => 'required|captcha:login',
```

❤️ 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/overtrue/laravel-package/issues).
2. Answer questions or fix bugs on the [issue tracker](https://github.com/overtrue/laravel-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.*

PHP 扩展包开发
---------

[](#php-扩展包开发)

> 想知道如何从零开始构建 PHP 扩展包？
>
> 请关注我的实战课程，我会在此课程中分享一些扩展开发经验 —— [《PHP 扩展包实战教程 - 从入门到发布》](https://learnku.com/courses/creating-package)

License
-------

[](#license)

MIT

###  Health Score

45

—

FairBetter than 91% of packages

Maintenance68

Regular maintenance activity

Popularity32

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 89.5% 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 ~244 days

Recently: every ~293 days

Total

6

Last Release

473d ago

Major Versions

1.x-dev → 2.0.02022-02-10

2.2.0 → 3.0.02025-03-19

### 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 (17 commits)")[![astro2049](https://avatars.githubusercontent.com/u/45759373?v=4)](https://github.com/astro2049 "astro2049 (2 commits)")

###  Code Quality

TestsPHPUnit

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/overtrue-laravel-qcloud-captcha/health.svg)

```
[![Health](https://phpackages.com/badges/overtrue-laravel-qcloud-captcha/health.svg)](https://phpackages.com/packages/overtrue-laravel-qcloud-captcha)
```

###  Alternatives

[markwalet/nova-modal-response

A Laravel Nova asset for Modal responses on an action.

17878.9k](/packages/markwalet-nova-modal-response)[overtrue/laravel-qcloud-federation-token

QCloud COS FederationToken generator for Laravel.

179.5k](/packages/overtrue-laravel-qcloud-federation-token)[crumbls/layup

A visual page builder plugin for Filament 5 — Divi-style grid layouts with extensible widgets.

592.7k2](/packages/crumbls-layup)[team-nifty-gmbh/tall-datatables

Server-side rendered datatables for Laravel and Livewire

1320.9k4](/packages/team-nifty-gmbh-tall-datatables)[tomshaw/electricgrid

A feature-rich Livewire package designed for projects that require dynamic, interactive data tables.

119.4k](/packages/tomshaw-electricgrid)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)