laravel-captcha

适用于 Laravel 的验证码服务，支持 GD 和 ImageMagick 两种图像库。

环境需求

• PHP ^8.2
• PHP GD 扩展（需支持 FreeType）
• Laravel ^12.0 | ^13.0

如果希望使用 ImageMagick 代替 GD，需安装 PHP Imagick 扩展（支持 PNG 格式）。

安装

composer require larva/laravel-captcha -vv

发布配置和字体文件

安装后，建议发布配置文件和字体文件到项目目录，以便自定义：

# 发布配置文件到 config/captcha.php
php artisan vendor:publish --tag=captcha-config

# 发布字体文件到 resources/fonts/
php artisan vendor:publish --tag=captcha-fonts

配置

发布配置文件后，可在 config/captcha.php 中调整以下参数：

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | testLimit | int | 3 | 同一验证码最多可验证次数，超过后自动刷新。设为 0 表示不限制 | | width | int | 120 | 验证码图片宽度（像素） | | height | int | 50 | 验证码图片高度（像素） | | padding | int | 2 | 文字与图片边缘的内边距（像素） | | backColor | int | 0xFFFFFF | 背景颜色（十六进制），默认白色 | | foreColor | int | 0x2040A0 | 字体颜色（十六进制），默认蓝色 | | transparent | bool | false | 是否使用透明背景 | | minLength | int | 6 | 验证码最小长度 | | maxLength | int | 7 | 验证码最大长度 | | offset | int | -2 | 字符间距，增大可提高可读性 | | fontFile | string | resource_path('fonts/SpicyRice.ttf') | TrueType 字体文件路径 | | imageLibrary | string | 'gd' | 图像渲染库，可选 'gd' 或 'imagick'，留空则自动检测 |

使用

1. 显示验证码

安装后自动注册路由，直接访问即可输出验证码图片：

GET /captcha

在表单中引用：

<img src="https://raw.githubusercontent.com/larvatecn/laravel-captcha/refs/heads/main/captcha" alt="captcha" onclick="this.src='/captcha?v='+Math.random()">

点击图片即可刷新验证码。

2. AJAX 刷新验证码

通过添加 refresh 参数可以获取新的验证码信息（JSON 格式）：

GET /captcha?refresh

返回内容：

{
    "hash1": 623,
    "hash2": 623,
    "url": "http://your-domain/captcha?v=665a1b2c3d4e5"
}

使用返回的 url 更新图片 src 属性即可刷新验证码。

3. 表单验证

方式一：使用自定义验证规则（推荐）

包中注册了 captcha 验证规则，可直接在验证规则中使用：

$validatedData = $request->validate([
    'captcha' => 'required|captcha',
]);

方式二：手动验证

通过 Captcha Facade 手动验证用户输入：

use Larva\Captcha\Captcha;

if (Captcha::validate($request->input('captcha'), false)) {
    // 验证通过
}

4. 在测试环境固定验证码

在 phpunit 等测试环境中，验证器会自动将验证码固定为 1234，方便编写自动化测试。

也可以手动设置固定验证码：

use Larva\Captcha\Captcha;

Captcha::setFixedVerifyCode('test-code');

License

MIT License