# captcha

**Repository Path**: fiberphp/captcha

## Basic Information

- **Project Name**: captcha
- **Description**: 🔢 FiberPHP 验证码组件 —— 图形验证码与滑块验证码，支持防重放、自定义样式，集成 Session。
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-23
- **Last Updated**: 2026-11-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🔢 FiberPHP 验证码组件

图形验证码与滑块验证码，支持防重放、自定义样式。

## 目录结构

```
src/
├── Captcha.php                # 统一入口
├── Contract/
│   └── DriverInterface.php    # 驱动契约
└── Driver/
    ├── ImageDriver.php         # 图形验证码（GD 绘制）
    └── SliderDriver.php        # 滑块验证码
config/
└── captcha.php                # 配置文件
tests/
├── CaptchaTest.php            # 8 个测试用例
└── bootstrap.php
```

## 安装

```bash
composer require fiberphp/captcha
```

安装后通过 `PackageManifest` 自动注册 Provider；包内置 `config/captcha.php` 默认配置随包自动合并，装包即用，应用在自己的 `config/captcha.php` 放同名键即可覆盖。

## 配置

`config/captcha.php`（默认值随包合并）：

```php
return [
    'default' => 'image',
    'drivers' => [
        'image' => [
            'driver' => 'image',
            'width' => 120,
            'height' => 40,
            'length' => 4,
            'font' => 5,
            'noise' => 30,
            'curve' => true,
            'expire' => 300,
        ],
        'slider' => [
            'driver' => 'slider',
            'width' => 300,
            'height' => 150,
            'slider_width' => 50,
            'tolerance' => 5,
            'expire' => 300,
        ],
    ],
];
```

## 快速开始

### 图形验证码

```php
// 生成（返回 key + base64 图片）
$captcha = captcha()->image();
// {"key":"captcha_abc123","image":"data:image/png;base64,..."}

// 前端展示
<img src="<?= $captcha['image'] ?>" alt="验证码">

// 验证（大小写不敏感，验证后自动销毁）
if (captcha()->verify($captcha['key'], $userInput)) {
    // 验证通过
}
```

### 滑块验证码

```php
// 生成（返回背景图 + 滑块图）
$captcha = captcha()->slider();
// {"key":"slider_xyz789","bg":"data:...","slider":"data:..."}

// 前端拖动后验证
if (captcha()->verify($captcha['key'], $dragX)) {
    // 验证通过（容差范围内）
}
```

### 助手函数

```php
captcha()->image();
captcha()->slider();
captcha()->verify($key, $input);
```

## API

### Captcha

| 方法                   | 说明                                           |
|------------------------|------------------------------------------------|
| `image()`              | 生成图形验证码，返回 `['key', 'image']`        |
| `slider()`             | 生成滑块验证码，返回 `['key', 'bg', 'slider']` |
| `verify($key, $input)` | 验证输入，验证后销毁                           |

### ImageDriver

- 随机 4 位字母数字
- GD 绘制 + 噪点干扰 + 曲线干扰
- 防时序攻击（`hash_equals`）
- 一次性验证（验证后销毁）

### SliderDriver

- GD 生成渐变背景 + 滑块拼图
- 容差验证（默认 ±5px）
- 一次性验证

## 测试

```bash
composer install
./vendor/bin/phpunit
```

## License

MIT