README

适用于 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="/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

larva / laravel-captcha

Maintainers

Package info

Statistics

Security