chleniang/cls-captcha

适用于 TP6/TP8 的验证码库；尤其适用于API开发，不使用session的场景；基于 think-captcha 改写;

v1.0.3 2024-08-23 03:19 UTC

Requires

• php: >=8.0.2
• ext-gd: *
• ext-mbstring: *
• topthink/framework: ^6.0|^8.0

MulanPSL-2.0

• chleniang

README

适用于 ThinkPHP6 / ThinkPHP8 的验证码库；

尤其适用于API开发，不使用session的场景；

基于 think-captcha 改写；

需求

• php : ^8.0.2
• topthink/framework : ^6.0|^8.0

特点

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

安装

# composer安装
composer require chleniang/cls-captcha

配置

配置文件 config/cls_captcha.php

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

使用

基本流程是：

• 使用 create() 方法创建验证码，返回 "存储KEY" 及 "BASE64图像"；
• 使用 check() 方法根据 "存储KEY" 及 "验证码" 进行校验；

create()

创建验证码

创建验证码，会返回 "存储KEY" 及 "BASE64图像数据"。

• "存储KEY" 需返回给前端，前端在表单提交时一同提交（后端以此去查找记录）
• "BASE64图像" 用于前端展示

• 方法定义

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

• 参数说明

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

• 返回值：array

  返回值示例：

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

• 使用示例

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

• 补充用法

  /*
  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" 及 "验证码" 进行校验。

• 方法定义

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

• 参数说明

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

• 返回值：bool

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

• 使用示例

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

• 补充用法

  // 本库定义有函数，可直接使用
  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() 方法前也需要指定相同的存储标识，否则无法找到验证码数据

• 方法定义

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

• 参数说明

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

• 返回值 $this

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

• 使用示例

  // 直接使用门面类
  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

  /* 
     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" => "错误信息"
           ]
  */
  

• 自定义路由

  /*
     在当前应用 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)