PHPackages                             zxf/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. [Validation & Sanitization](/categories/validation)
4. /
5. zxf/captcha

ActiveLibrary[Validation & Sanitization](/categories/validation)

zxf/captcha
===========

高性能滑动验证码 PHP 扩展包，支持 Laravel、ThinkPHP 等主流框架

v1.0.7(1mo ago)1036↓50%MITPHPPHP >=8.2

Since Apr 1Pushed 1mo agoCompare

[ Source](https://github.com/zhaoxianfang/captcha)[ Packagist](https://packagist.org/packages/zxf/captcha)[ Docs](https://github.com/zhaoxianfang/captcha)[ RSS](/packages/zxf-captcha/feed)WikiDiscussions master Synced 4w ago

READMEChangelog (9)Dependencies (2)Versions (10)Used By (0)

xfCaptcha - 高性能滑动验证码 & 点击验证码 PHP 扩展包
========================================

[](#xfcaptcha---高性能滑动验证码--点击验证码-php-扩展包)

[![PHP Version](https://camo.githubusercontent.com/d840cef9807c8f76051ad687841d67f4d830c84e0d83236968e53124ef6742d5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344382e322d3838393242462e737667)](https://php.net/)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE)![Version](https://camo.githubusercontent.com/255109593c502f86fcdeadf339eb869040c10da70d55d059a83e1665fc24f83d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d312e302e362d627269676874677265656e2e737667)

高性能、安全、易用的滑动验证码 & 点击验证码 PHP 扩展包，支持 Laravel、ThinkPHP 等主流 PHP 框架，也可在原生 PHP 中使用。

- **滑动验证码**：拖动拼图滑块完成验证
- **点击验证码**：按顺序点击图片中的文字/符号完成验证
- **双模式随机**：支持两种验证码随机展示，增强安全性

效果展示
----

[](#效果展示)

- 滑动验证码示例

[![滑动验证码演示](example/demo1.jpg)](example/demo1.jpg)

- 点击验证码示例

[![点击验证码演示](example/demo2.jpg)](example/demo2.jpg)

✨ 特性
----

[](#-特性)

- 🚀 **高性能**: 优化的图像处理算法，响应迅速
- 🔒 **高安全性**: 支持双重验证模式，容错机制、错误次数限制、防暴力破解、请求指纹绑定
- 🤖 **防机器人**: 滑动轨迹验证，检测异常操作行为
- 🎨 **美观界面**: 现代化 UI 设计，支持浅色/深色主题
- 📱 **响应式**: 完美适配各种屏幕尺寸，移动端优化
- 🔧 **易集成**: 支持 Laravel 11+、ThinkPHP 8+ 等主流框架
- 🌍 **兼容性**: 支持 PHP 8.2 / 8.3 / 8.4 / 8.5，不依赖任何第三方包
- ⚡ **轻量化**: 无外部依赖，安装即用
- 🛡️ **防重放**: Token 一次性使用，防止重放攻击
- 🔄 **易重置**: 提供 reset() 接口，表单失败后快速重置
- 🎯 **双模式**: 滑动验证码 + 点击验证码，支持随机切换
- 📝 **中文支持**: 点击验证码支持中文汉字和符号，自动检测系统字体
- 🔐 **安全随机**: 全面使用 `random_int` 替代 `mt_rand`，符合密码学安全要求

📋 环境要求
------

[](#-环境要求)

- PHP >= 8.2
- GD 扩展
- Laravel 11+ 或 ThinkPHP 8+（可选）

📦 安装
----

[](#-安装)

通过 Composer 安装：

```
composer require zxf/captcha
```

🚀 快速开始
------

[](#-快速开始)

### Laravel 中使用（支持 Laravel 11+）

[](#laravel-中使用支持-laravel-11)

#### 1. 安装服务提供者（Laravel 11+ 会自动发现）

[](#1-安装服务提供者laravel-11-会自动发现)

**注意：本包需要 Laravel 11.0 或更高版本。**

对于需要手动注册的情况，在 `bootstrap/providers.php` 中注册服务提供者：

```
return [
    // ...
    zxf\Captcha\Laravel\CaptchaServiceProvider::class,
];
```

#### 2. 发布配置文件

[](#2-发布配置文件)

```
php artisan vendor:publish --tag=xf-captcha-config
```

#### 3. 在 Blade 模板中使用

[](#3-在-blade-模板中使用)

Laravel 11 中引入 xfCaptcha 有三种方式：

**方式一：使用 Blade 组件（推荐）**

使用 `@include` 引入 Blade 组件，会自动在当前位置加载 CSS 和 JS 资源：

```

    验证码演示

        @csrf

        @include('xf-captcha::captcha', [
            'selector' => '.xf-captcha',
            'placeholder' => '点击完成验证',
            'inputName' => 'xf_captcha',
            'width' => '100%',
            'height' => '40px',
            'borderRadius' => '4px',
            'onSuccess' => 'function(token) { console.log("验证成功", token); }',
            'onFail' => 'function() { console.log("验证失败"); }',
            'onClose' => 'function() { console.log("弹窗关闭"); }',
        ])

        提交

        // 表单提交示例
        document.getElementById('loginForm').addEventListener('submit', function(e) {
            e.preventDefault();

            fetch('/login', {
                method: 'POST',
                body: new FormData(this)
            })
            .then(response => response.json())
            .then(data => {
                if (data.success) {
                    alert('登录成功！');
                    window.location.href = '/dashboard';
                } else {
                    alert('登录失败：' + data.message);
                    // 重置验证码
                    xfCaptcha.reset();
                }
            });
        });

```

> **注意**：Blade 组件会在 `@include` 的位置直接输出 `` 和 `` 标签。如果你需要将 JS 放在页面底部，请使用方式二手动引入资源。

**方式二：手动引入资源（需要自定义时）**

如果需要更多自定义控制（例如把 JS 放到页面底部），可以手动引入 CSS 和 JS：

```

    验证码演示

        @csrf

        提交

        // 手动初始化
        xfCaptcha.init({
            handleDom: '#my-captcha',
            dataUrl: '{{ route('xf-captcha.data') }}',
            checkUrl: '{{ route('xf-captcha.check') }}',
            placeholder: '点击完成验证',
            inputName: 'xf_captcha',
            theme: 'auto'
        });

        // 表单提交
        document.getElementById('loginForm').addEventListener('submit', function(e) {
            e.preventDefault();

            fetch('/login', {
                method: 'POST',
                body: new FormData(this)
            })
            .then(response => response.json())
            .then(data => {
                if (data.success) {
                    alert('登录成功！');
                } else {
                    alert('登录失败：' + data.message);
                    xfCaptcha.reset();
                }
            });
        });

```

**方式三：使用资源混合（Laravel Mix/Vite）**

如果使用 Laravel Mix 或 Vite 构建前端资源：

```
// resources/js/app.js
import 'zxf/captcha/resources/assets/js/captcha';
import 'zxf/captcha/resources/assets/css/captcha.css';

// 初始化验证码
document.addEventListener('DOMContentLoaded', function() {
    xfCaptcha.init({
        handleDom: '.xf-captcha',
        dataUrl: '/xf_captcha/data',
        checkUrl: '/xf_captcha/check',
        inputName: 'xf_captcha'
    });
});
```

然后在 Blade 模板中：

```

    验证码演示
    @vite(['resources/css/app.css', 'resources/js/app.js'])

        @csrf

        提交

```

#### Blade 组件参数说明

[](#blade-组件参数说明)

使用 `@include('xf-captcha::captcha', [...])` 时可以传入以下参数：

参数类型默认值说明`selector`string自动生成触发元素的选择器`placeholder`string`点击按钮进行验证`触发按钮的占位文字`slideText`string`拖动左边滑块完成上方拼图`滑动提示文字`clickText`string`请按照顺序点击图片中的文字`点击提示文字`successText`string`✓ 验证成功`验证成功提示`failText`string`验证失败，请重试`验证失败提示`inputName`string`xf_captcha_token`隐藏输入框的 `name` 属性`autoInsertInput`bool`true`验证成功后是否自动插入隐藏输入框`theme`string`auto`主题：`light`、`dark`、`auto``showClose`bool`true`是否显示关闭按钮`showRefresh`bool`true`是否显示刷新按钮`showRipple`bool`true`是否显示水波纹效果`width`string—自定义触发按钮宽度（如 `100%`、`260px`）`height`string—自定义触发按钮高度（如 `40px`）`borderRadius`string—自定义触发按钮圆角（如 `4px`）`onSuccess`string—验证成功回调函数字符串，如 `function(token) { ... }``onFail`string—验证失败回调函数字符串`onClose`string—弹窗关闭回调函数字符串`attributes`string—额外的 HTML 属性字符串#### 4. 后端验证

[](#4-后端验证)

```
use Illuminate\Http\Request;

public function login(Request $request)
{
    // 验证请求
    $validated = $request->validate([
        'email' => 'required|email',
        'password' => 'required',
        'xf_captcha' => 'required|xfCaptcha', // 验证验证码
    ], [
        'xf_captcha.required' => '请完成验证',
        'xf_captcha.xf_captcha' => '验证失败，请重新验证',
    ]);

    // 登录逻辑...
}
```

### ThinkPHP 中使用（支持 ThinkPHP 8+）

[](#thinkphp-中使用支持-thinkphp-8)

#### 1. 配置

[](#1-配置)

在 `config/service.php` 中添加：

```
return [
    // ...
    'services' => [
        zxf\Captcha\ThinkPHP\CaptchaService::class,
    ],
];
```

#### 2. 发布配置

[](#2-发布配置)

```
php think vendor:publish zxf/captcha
```

#### 3. 在模板中使用

[](#3-在模板中使用)

```
>

    验证码演示

        提交

        xfCaptcha.init({
            handleDom: '.xf-captcha',
            dataUrl: '/xf_captcha/data',
            checkUrl: '/xf_captcha/check',
            inputName: 'xf_captcha_token'
        });

        // 表单提交
        document.getElementById('loginForm').addEventListener('submit', function(e) {
            e.preventDefault();

            fetch('/login', {
                method: 'POST',
                body: new FormData(this)
            })
            .then(response => response.json())
            .then(data => {
                if (data.code === 200) {
                    alert('登录成功！');
                } else {
                    alert('登录失败：' + data.msg);
                    xfCaptcha.reset(); // 重置验证码
                }
            });
        });

```

#### 4. 后端验证

[](#4-后端验证-1)

```
use zxf\Captcha\Captcha;

public function login()
{
    $data = input('post.');

    // 验证验证码
    $captcha = app('xfCaptcha');
    $result = $captcha->verify(null, $data['xf_captcha_token'] ?? '');

    if (!$result['success']) {
        return json(['code' => 400, 'msg' => $result['message']]);
    }

    // 登录逻辑...
}
```

### 原生 PHP 中使用

[](#原生-php-中使用)

```