chleniang/cls-captcha

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

Maintainers

Details

gitee.com/chleniang/cls-captcha

Installs: 1

Dependents: 0

Suggesters: 0

Security: 0

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

Requires

MulanPSL-2.0 98793cab19605165ccb036bd05f2a21311ca1cac

  • chleniang <chleniang.woop@163.com>

This package is not auto-updated.

Last update: 2024-10-22 05:17:14 UTC

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