# cls-captcha

**Repository Path**: chleniang/cls-captcha

## Basic Information

- **Project Name**: cls-captcha
- **Description**: 适用于 TP6/TP8 的验证码库；尤其适用于API开发，不使用session的场景；基于 think-captcha 改写;
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2024-08-21
- **Last Updated**: 2025-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: ThinkPHP, think-captcha, Captcha, 验证码, API

## README

# CLS-Captcha

> 适用于 `ThinkPHP6` / `ThinkPHP8` 的验证码库；
>
> 尤其适用于API开发，不使用session的场景；
>
> 基于 `think-captcha` 改写；



## 需求

- `php : ^8.0.2`
- `topthink/framework : ^6.0|^8.0`



## 特点

- 配置及基本用法同 `think-captcha` 一样，降低使用成本
- 使用缓存存储生成的数据
- 可自由指定缓存存储标识，更为灵活



## 安装

```shell
# composer安装
composer require chleniang/cls-captcha
```



## 配置

> 配置文件 `config/cls_captcha.php`
>
> 配置项完全同 `think-captcha` 一样，请参考官方手册或查看配置文件注释说明



## 使用

> 基本流程是：
>
> - 使用 `create()` 方法创建验证码，返回 "存储KEY" 及 "BASE64图像"；
> - 使用 `check()` 方法根据 "存储KEY" 及 "验证码" 进行校验；



### `create()` 

创建验证码

> 创建验证码，会返回 "存储KEY" 及 "BASE64图像数据"。
>
> - "存储KEY" 需返回给前端，前端在表单提交时一同提交（后端以此去查找记录）
> - "BASE64图像" 用于前端展示

- 方法定义

  ```php
  public function create(
      string|null $config = null
  ): array
  ```

- 参数说明

  - `$config`  `{string|null}`  自定义配置标识（`默认null` ：不使用自定义配置）

- 返回值：`array`

  > 返回值示例：
  >
  > ```php
  > [
  >      "key" => "4b3e8f71......",  // 存储KEY（需返回给前端，前端在表单提交时一同提交）
  >      "img" => "data:image/png;base64,iBORwA......"  // BASE64图像数据（前端验证码图片展示）
  > ]
  > ```

- 使用示例

  ```php
  // 直接使用门面类
  use chleniang\ClsCaptcha\facade\Captcha;
  
  // 生成验证码，可直接将结果数组返回给前端；
  $result = Captcha::create();
  return json([
      'code' => 0,
      'data' => $result
  ]);
  
  ```

- 补充用法

  ```php
  /*
  1.本库定义有直接访问路由，前端也可直接访问 URL  
   	URL格式为：  /cls_captcha/[:config]
         [:config] 即为 自定义配置标识
      最为简单的是直接访问  /cls_captcha  即可
      返回  [ 
              "code" => 0,  // 0:成功  非0:失败
              "data" => [
                "key"=>"4b3e8f...",  // 验证码KEY
                "img"=>"data:image/png;base64,iVBORw..."  // BASE64图像
              ]
            ]
  */
  
  
  // 2.本库也定义有函数，可直接使用
  function cls_captcha(
      string|null $config = null,
      string|null $storeKey = null
  ): array
  /*
     $config    自定义配置标识
     $storeKey  缓存存储标识(null使用默认缓存)
     返回  [ 
             "key"=>"4b3e8f...", 
             "img"=>"data:image/png;base64,iVBORw..."
           ]
   */
  ```



### `check()`

校验验证码

> 根据 "存储KEY" 及 "验证码" 进行校验。

 - 方法定义

  ```php
  public function check(
      string $cacheKey, 
      string $code
  ): bool
  ```

- 参数说明

  - `$cacheKey`  `{string}`  存储KEY（在`create()` 时生成，返回给前端的）
  - `$code`  `{string}`  用户验证码（用户填写的）

- 返回值：`bool`

  > 校验成功返回 `true`    失败返回 `false`
  >

- 使用示例

  ```php
  // 直接使用门面类
  use chleniang\ClsCaptcha\facade\Captcha;
  
  // 前端提交数据
  $captchaKey = request()->param('captcha_key','');
  $captchaCode = request()->param('captcha_code','');
  $checkRes = Captcha::check($captchaKey, $captchaCode);
  if(!$checkRes){
      // 校验失败，返回错误提示
  }
  // captcha校验通过
  
  ```
  
- 补充用法

  ```php
  // 本库定义有函数，可直接使用
  function cls_captcha_check(
      string $cacheKey,
      string $code,
      string|null $storeKey = null
  ): array
  /*
     $cacheKey  存储KEY
     $code      用户验证码
     $storeKey  缓存存储标识(null使用默认缓存)
     返回  true:校验通过   false:校验不通过
  */
  ```



### `store()`

指定存储标识

> 因为本库是使用缓存存储验证码数据的，为适应更多用户需求，提供此方法
>
> （当然，不使用此方法也行，将使用默认缓存存储）
>
> - 此方法需在 `create()` 或 `check()` 方法之前调用
> - 如果在  `create()` 生成验证码方法前指定了存储标识，那么在 `check()` 方法前也需要指定相同的存储标识，否则无法找到验证码数据

-  方法定义

  ```php
  function store(
      string|null $storeKey = null
  ): static
  ```

- 参数说明

  - `$storeKey`  `{string|null}`  缓存存储标识（`null` 使用默认缓存）

- 返回值  `$this`

  > 返回类实例本身，方便调用后续方法

- 使用示例

  ```php
  // 直接使用门面类
  use chleniang\ClsCaptcha\facade\Captcha;
  
  // 假设此处使用 "rds2" 缓存存储标识（前提是确实有此缓存标识）
  
  // 生成验证码数据
  $result = Captcha::store('rds2')->create();
  // 也可直接使用cls_captcha()函数，第二个参数即是缓存存储标识
  // $result = cls_captcha(null, 'rds2');
  
  return json([
      'code' => 0,
      'data' => $result
  ]);
  
  
  // 前端提交数据
  $captchaKey = request()->param('captcha_key','');
  $captchaCode = request()->param('captcha_code','');
  
  $checkRes = Captcha::store('rds2')->check($captchaKey, $captchaCode);
  // 也可直接使用cls_captcha_check()函数，第三个参数即是缓存存储标识
  // checkRes = cls_captcha_check($captchaKey, $captchaCode, 'rds2')
  
  if(!$checkRes){
      // 校验失败，返回错误提示
  }
  // captcha校验通过
  
  ```

- 补充说明

  > 在 `cls_captcha()` 及 `cls_captcha_check()` 函数中的最后一个参数 `$storeKey` 就是指此方法中的缓存存储标识参数



### 路由

> 路由实际就是指向 `\chleniang\ClsCaptcha\CaptchaController 控制器的 index 方法`

- 本库定义有直接访问路由，前端也可直接访问 URL

  ```php
  /* 
     URL格式为：  /cls_captcha/[:config]
         [:config] 即为 自定义配置标识
     最为简单的是直接访问  /cls_captcha  即可
     成功返回
          [ 
             "code" => 0,  // 0:成功  非0:失败
             "data" => [
               "key"=>"4b3e8f...",  // 验证码KEY
               "img"=>"data:image/png;base64,iVBORw..."  // BASE64图像
             ]
           ]
     出错返回
          [ 
             "code" => 995,  // 0:成功  非0:失败
             "data" => [],
             "msg" => "错误信息"
           ]
  */
  ```

- 自定义路由

  ```php
  /*
     在当前应用 route/xxx.php 路由规则文件中添加以下路由规则
     直接 GET 访问  /my_captcha  即可
     成功返回
          [ 
             "code" => 0,  // 0:成功  非0:失败
             "data" => [
               "key"=>"4b3e8f...",  // 验证码KEY
               "img"=>"data:image/png;base64,iVBORw..."  // BASE64图像
             ]
           ]
     出错返回
          [ 
             "code" => 995,  // 0:成功  非0:失败
             "data" => [],
             "msg" => "错误信息"
           ]
  */
  Route::rule(
      '/my_captcha',
      "\\chleniang\\ClsCaptcha\\CaptchaController@index"
  )->method('GET');
  ```



## Lisence

- [木兰宽松许可证,第2版 (Mulan PSL v2)](http://license.coscl.org.cn/MulanPSL2)