README

ThinkPHP 8 图形验证码扩展，一比一还原 EasyCaptcha 视觉效果。

支持 PNG 静态、GIF 动态、算术、中文、中文 GIF 五种验证码类型，内置 10 种英文字体，支持 Session 模式和 API 前后端分离模式。

效果预览

类型	示例
PNG 静态 (SpecCaptcha)
GIF 动态 (GifCaptcha)
算术 (ArithmeticCaptcha)
中文 (ChineseCaptcha)
中文GIF (ChineseGifCaptcha)

环境要求

PHP >= 8.0
ext-gd
ThinkPHP >= 8.0

安装

composer require kqdog/mn-captcha

安装完成后，包会通过 ThinkPHP 的服务发现机制 自动注册，无需手动配置。

快速开始

安装后即可直接在浏览器访问验证码图片：

http://your-domain/captcha

模板中使用

<!-- 输出验证码 img 标签（点击可刷新） -->
<div>{:captcha_img()}</div>

<!-- 或使用 src -->
<div><img src="{:captcha_src()}" alt="captcha" onclick="this.src='{:captcha_src()}?'+Math.random()" /></div>

控制器中使用

<?php
namespace app\controller;

class Login
{
    // 输出验证码图片
    public function captcha()
    {
        return captcha();
    }

    // 使用指定配置输出
    public function gifCaptcha()
    {
        return captcha('gif');
    }
}

验证码校验

方式一：ThinkPHP 验证器

$this->validate($data, [
    'captcha|验证码' => 'require|captcha'
]);

方式二：手动校验

if (!captcha_check($captcha)) {
    // 验证失败
}

配置

发布配置文件（安装时自动发布到 config/captcha.php）：

<?php
return [
    // 验证码类型：spec | gif | chinese | chinese_gif | arithmetic
    'type'     => 'spec',
    // 验证码位数
    'length'   => 5,
    // 图片宽度
    'width'    => 130,
    // 图片高度
    'height'   => 48,
    // 字体大小
    'fontSize' => 32.0,
    // 字符类型：1-混合 2-纯数字 3-纯字母 4-纯大写 5-纯小写 6-数字大写
    'charType' => 1,
    // 内置字体 0~9
    'font'     => 0,
    // 验证码过期时间(秒)
    'expire'   => 1800,
    // 是否使用 API 模式
    'api'      => false,

    // 多配置示例 —— 通过 captcha('gif') 调用
    'gif' => [
        'type'   => 'gif',
        'length' => 5,
    ],
    'arithmetic' => [
        'type'   => 'arithmetic',
        'length' => 2,
    ],
    'chinese' => [
        'type'   => 'chinese',
        'length' => 4,
    ],
    'chinese_gif' => [
        'type'   => 'chinese_gif',
        'length' => 4,
    ],
];

多配置使用

在配置文件中定义子配置后，通过 URL 或函数参数切换：

http://your-domain/captcha/gif
http://your-domain/captcha/arithmetic
http://your-domain/captcha/chinese

或在代码中：

return captcha('gif');
return captcha('arithmetic');

验证码类型

1. SpecCaptcha — PNG 静态

默认类型，生成 PNG 格式的静态验证码图片。

'type' => 'spec'

2. GifCaptcha — GIF 动态

生成 GIF 动画验证码，字符透明度逐帧渐变。

'type' => 'gif'

3. ArithmeticCaptcha — 算术

生成形如 3+5=? 的算术验证码，用户需输入计算结果。

'type' => 'arithmetic',
'length' => 2,  // 参与运算的数字个数

4. ChineseCaptcha — 中文

生成中文字符的静态 PNG 验证码。

'type' => 'chinese',
'length' => 4,

5. ChineseGifCaptcha — 中文 GIF

中文字符 + GIF 动画效果。

'type' => 'chinese_gif',
'length' => 4,

内置字体

常量	编号	字体
`Captcha::FONT_1`	0	actionj
`Captcha::FONT_2`	1	epilog
`Captcha::FONT_3`	2	fresnel
`Captcha::FONT_4`	3	headache
`Captcha::FONT_5`	4	lexo
`Captcha::FONT_6`	5	prefix
`Captcha::FONT_7`	6	progbot
`Captcha::FONT_8`	7	ransom
`Captcha::FONT_9`	8	robot
`Captcha::FONT_10`	9	scandal

配置字体：

'font' => 3,  // 使用 headache 字体

字符类型

常量	值	说明
`Captcha::TYPE_DEFAULT`	1	数字和字母混合
`Captcha::TYPE_ONLY_NUMBER`	2	纯数字
`Captcha::TYPE_ONLY_CHAR`	3	纯字母
`Captcha::TYPE_ONLY_UPPER`	4	纯大写字母
`Captcha::TYPE_ONLY_LOWER`	5	纯小写字母
`Captcha::TYPE_NUM_AND_UPPER`	6	数字和大写字母

'charType' => 2,  // 纯数字验证码

API 模式（前后端分离）

开启 API 模式后，captcha() 返回 JSON 数组而非图片响应，适用于前后端分离项目。

配置

// config/captcha.php
return [
    'api' => true,
    // ...其他配置
];

// 也可以单独配置某个类型为 API 模式
return [
    'api_spec' => [
        'type' => 'spec',
        'api'  => true,
    ],
];

获取验证码（API）

请求：

GET /captcha

响应：

{
    "key": "captcha_6621a3b2c4e5f1.23456789",
    "img": "data:image/png;base64,iVBORw0KGgo..."
}

key：验证码唯一标识，校验时需回传
img：Base64 编码的图片，可直接用于 <img src="...">

前端使用

<img id="captchaImg" src="" />
<input type="text" id="captchaCode" placeholder="请输入验证码" />
<input type="hidden" id="captchaKey" />

<script>
// 获取验证码
fetch('/captcha')
    .then(r => r.json())
    .then(data => {
        document.getElementById('captchaImg').src = data.img;
        document.getElementById('captchaKey').value = data.key;
    });

// 提交验证
function verify() {
    fetch('/login', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            code: document.getElementById('captchaCode').value,
            captcha_key: document.getElementById('captchaKey').value
        })
    });
}
</script>

后端校验（API）

public function login(Request $request)
{
    $code = $request->post('code');
    $key  = $request->post('captcha_key');

    if (!captcha_check($code, $key)) {
        return json(['code' => 1, 'msg' => '验证码错误']);
    }

    // 验证通过，继续登录逻辑...
}

Facade 使用

use kqdog\captcha\facade\Captcha;

// 创建验证码
Captcha::create();         // 默认配置
Captcha::create('gif');    // 指定配置

// 校验验证码
Captcha::check($code);            // Session 模式
Captcha::check($code, $key);      // API 模式

独立使用验证码类

如果不需要 ThinkPHP 集成，可以直接使用验证码类生成图片：

use kqdog\captcha\SpecCaptcha;
use kqdog\captcha\GifCaptcha;
use kqdog\captcha\ArithmeticCaptcha;
use kqdog\captcha\Captcha;

// PNG 验证码
$captcha = new SpecCaptcha(130, 48, 5);
$captcha->setFont(Captcha::FONT_2);
$captcha->setCharType(Captcha::TYPE_NUM_AND_UPPER);

$text = $captcha->text();    // 验证码文本
$img  = $captcha->out();     // PNG 二进制
$b64  = $captcha->toBase64(); // data:image/png;base64,...

// GIF 动态验证码
$gif = new GifCaptcha(130, 48, 5);
$data = $gif->out();

// 算术验证码
$arith = new ArithmeticCaptcha(130, 48, 2);
$arith->text();    // 返回计算结果，如 "8"
$arith->getArithmeticString(); // 返回算式，如 "3+5=?"

辅助函数

函数	说明
`captcha($config)`	输出验证码（图片响应或 API 数组）
`captcha_src($config)`	获取验证码图片 URL
`captcha_img($id, $domid)`	输出验证码 `<img>` 标签（点击刷新）
`captcha_check($code, $key)`	校验验证码

开源协议

Apache-2.0

kqdog / mn-captcha

Maintainers

Package info

Statistics

Security