Captcha for Laravel 11/12/13

一个为 Laravel 11/12/13 深度定制的现代化验证码组件。基于 Intervention Image v3 构建，采用模块化设计，易于扩展和维护。

特性

• PHP 8.2+ 强类型支持。
• Intervention Image v3：使用成熟的图像处理库，支持 GD 和 Imagick 驱动。
• 模块化架构：解耦了验证码生成（Generators）、配置管理（Support）和图像绘制（ImageCreator）。
• 性能优化：内置静态资源缓存（字体、背景图），显著减少磁盘 I/O。
• 无状态 API 支持：完美支持前后端分离项目。
• 高度可定制：预置 8 种验证码样式，支持自定义配置。
• 中文字符验证码：内置 ChineseGenerator，支持中文汉字验证码。
• 加密传输：支持 encrypt 选项，对验证码 key 进行加密后传输。

预览

生成全部 8 种样式预览：

php preview.php

default	math	number	flat	mini	inverse	admin	chinese

💡 预览图为随机生成，每次运行 php preview.php 会重新生成不同内容。

安装

通过 Composer 安装：

composer require "jason/captcha:^1.0"

在 Windows 环境下，确保 php.ini 中启用了 php_gd.dll 或 php_imagick.dll。

配置

发布配置文件：

php artisan vendor:publish --provider="Jason\Captcha\CaptchaServiceProvider" --tag="config"

config/captcha.php 中预置了 8 种验证码样式：default、math、number、flat、mini、inverse、admin、chinese。

每个样式可独立配置以下选项：

选项	类型	默认值	说明
length	int	4	验证码字符个数
width	int	120	图片宽度（px）
height	int	36	图片高度（px）
quality	int	90	JPEG 输出质量（0-100）
math	bool	false	算术模式，生成加减乘算式
expire	int	60	有效期（秒）
encrypt	bool	false	是否加密验证码 key 后传输
sensitive	bool	false	是否区分大小写
angle	int	15	字符最大旋转角度
lines	int	3	干扰线数量
lineWidth	int	1	干扰线宽度（px）
lineColor	string	#ff00ff	干扰线颜色（十六进制）
bgImage	bool	true	是否使用随机背景图片
bgColor	string	#ffffff	背景颜色（bgImage=false 时生效）
fontColors	array	—	字体颜色列表，每个字符随机选取
contrast	int	0	对比度调整（负值降低、正值增加）
sharpen	int	0	锐化强度
blur	int	0	模糊强度
invert	bool	false	反转图片颜色
characters	array	—	自定义字符集
marginTop	int	自动	文字上边距（px）
textLeftPadding	int	4	文字左边距（px）
fontsDirectory	string	包内路径	自定义字体目录
bgsDirectory	string	包内路径	自定义背景图目录

示例——math 样式（算术验证码）：

'math' => [
'length' => 9,
'width' => 120,
'height' => 36,
'quality' => 90,
'math' => true,
],

chinese 样式（中文字符验证码）：

'chinese' => [
'length' => 4,
'width' => 120,
'height' => 36,
'sensitive' => true,
'angle' => 20,
'lines' => 4,
],

使用方法

1. 传统 Session 模式

在视图中显示验证码：

<formmethod="POST" action="/register">
@csrf
<div>
{!! captcha_img() !!}
<inputtype="text" name="captcha" required></div><buttontype="submit">提交</button></form>

在控制器中进行验证：

publicfunctionstore(Request$request)
{
$request->validate([
'captcha' => 'required|captcha',
]);
// 验证通过后的逻辑...
}

2. 无状态 API 模式

获取验证码数据（JSON 响应）： GET /captcha/api/default

返回示例：

{
"sensitive": false,
"key": "$2y$10$...", "img": "data:image/jpeg;base64,..."
}

前端验证时，需将 key 一并传回后端：

publicfunctionapiStore(Request$request)
{
$request->validate([
'captcha' => 'required|captcha_api:' . $request->input('key') . ',default',
]);
// 验证通过后的逻辑...
}

辅助函数

• captcha(): 返回验证码图像响应。
• captcha_src(string $style = 'default'): 返回验证码图片的 URL 字符串。
• captcha_img(string $style = 'default', array $attrs = []): 返回验证码图片的 HTML <img> 标签。
• captcha_check(string $value): 手动验证 Session 模式下的验证码。
• captcha_api_check(string $value, string $key, string $style = 'default'): 手动验证 API 模式下的验证码。

架构

采用模块化分层设计，各层职责清晰、易于扩展：

层	类	职责
内容生成	CaptchaGenerator — StringGenerator、MathGenerator、ChineseGenerator	生成验证码内容（字符串、算术表达式、中文汉字）
图像渲染	ImageCreator	将内容绘制为验证码图片（背景/文字/干扰线/特效）
配置管理	Support/Config	合并全局配置与样式配置
核心编排	Captcha	协调生成与验证流程，支持 Session/API 两种模式
Facade	Facades/Captcha	提供简洁的静态访问接口

鸣谢

本项目基于原 mews/captcha 进行现代化重构。

协议

MIT License