Class yii\captcha\CaptchaAction

继承yii\captcha\CaptchaAction » yii\base\Action » yii\base\Component » yii\base\BaseObject
实现yii\base\Configurable
可用自版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/captcha/CaptchaAction.php

CaptchaAction 渲染一个验证码(CAPTCHA)图像.

CaptchaAction 与 yii\captcha\Captchayii\captcha\CaptchaValidator 一起使用, 以提供 CAPTCHA|验证码 功能.

通过配置 CaptchaAction 的属性, 你可以自定义生成的验证码(CAPTCHA)图像的外观, 如字体颜色, 背景颜色等.

Note: CaptchaAction 需要 GD2 扩展或 PHP ImageMagick 扩展.

使用验证码(CAPTCHA)涉及以下步骤:

  1. 重写 yii\web\Controller::actions() 并注册一个ID为captcha的 CaptchaAction 类的动作;
  2. 在表单模型中, 声明一个属性来存储用户输入的验证码, 并声明将由captcha验证器验证其值.
  3. 在控制器视图的表单中插入 yii\captcha\Captcha 小部件.

示例:

// Controller:
public function actions()
{
    return [
        'captcha' => [
            'class' => 'yii\captcha\CaptchaAction',
            'width' => 80,   // 图像宽度
            'height' => 34,  // 图像高度
        ],
    ];
}

// Model:
class LoginForm extends Model
{
    public $captcha;

    public function rules()
    {
        return [
            ['captcha', 'captcha'],
        ];
    }
}

// View:
echo $form->field($model, 'captcha')->widget(yii\captcha\Captcha::className(), [
    'captchaAction' => 'site/captcha',
    'imageOptions' => ['alt' => '点击换图', 'title' => '点击换图', 'class' => 'captcha'],
    'options' => ['class' => 'form-control', 'style' => 'width:80px;']
]);

公共属性

隐藏继承的属性

属性类型描述定义在
$backColor integer 背景颜色. yii\captcha\CaptchaAction
$behaviors yii\base\Behavior[] 附加到此组件的行为列表. 该属性是只读的. yii\base\Component
$controller yii\base\Controller|yii\web\Controller|yii\console\Controller 拥有此动作的控制器. yii\base\Action
$fixedVerifyCode string 固定的验证码. yii\captcha\CaptchaAction
$fontFile string TrueType 字体文件. yii\captcha\CaptchaAction
$foreColor integer 字体颜色. yii\captcha\CaptchaAction
$height integer 生成的验证码(CAPTCHA)图像的高度. yii\captcha\CaptchaAction
$id string 动作 ID. yii\base\Action
$imageLibrary string 要使用的渲染库. yii\captcha\CaptchaAction
$maxLength integer 随机生成的单词的最大长度. yii\captcha\CaptchaAction
$minLength integer 随机生成的单词的最小长度. yii\captcha\CaptchaAction
$offset integer 字符之间的偏移量. yii\captcha\CaptchaAction
$padding integer 在文本周围的填充. yii\captcha\CaptchaAction
$testLimit integer 应该显示相同验证码(CAPTCHA)的次数. yii\captcha\CaptchaAction
$transparent boolean 是否使用透明背景. yii\captcha\CaptchaAction
$uniqueId string 整个应用程序中此动作的唯一 ID. 该属性是只读的. yii\base\Action
$verifyCode string 验证码. 该属性是只读的. yii\captcha\CaptchaAction
$width integer 生成的验证码(CAPTCHA)图像的宽度. yii\captcha\CaptchaAction

公共方法

隐藏继承的方法

方法描述定义在
__call() 调用不是类方法的已命名方法. yii\base\BaseObject
__clone() 在通过克隆现有对象创建对象之后调用此方法. yii\base\Component
__construct() 构造函数. yii\base\Action
__get() 返回对象属性的值. yii\base\BaseObject
__isset() 检查属性是否已设置, 即已定义且不为null. yii\base\BaseObject
__set() 设置对象属性的值. yii\base\BaseObject
__unset() 将对象属性设置为null. yii\base\BaseObject
attachBehavior() 将行为附加到此组件. yii\base\Component
attachBehaviors() 将行为列表附加到组件. yii\base\Component
behaviors() 返回此组件应该具有的行为列表. yii\base\Component
canGetProperty() 返回一个值, 指示属性是否可读. yii\base\BaseObject
canSetProperty() 返回一个值, 指示属性是否可写. yii\base\BaseObject
className() 返回此类的完全限定名称. yii\base\BaseObject
detachBehavior() 从组件中分离一个行为. yii\base\Component
detachBehaviors() 分离组件中的所有行为. yii\base\Component
ensureBehaviors() 确保在 behaviors() 中声明的行为已附加到此组件. yii\base\Component
generateValidationHash() 生成可用于客户端验证的哈希码. yii\captcha\CaptchaAction
getBehavior() 返回指定的行为对象. yii\base\Component
getBehaviors() 返回附加到此组件的所有行为. yii\base\Component
getUniqueId() 返回整个应用程序中此动作的唯一 ID. yii\base\Action
getVerifyCode() 获取验证码. yii\captcha\CaptchaAction
hasEventHandlers() 返回一个值, 指示是否有任何处理程序附加到指定的事件. yii\base\Component
hasMethod() 返回一个值, 指示方法是否已定义. yii\base\BaseObject
hasProperty() 返回一个值, 指示属性是否已定义. yii\base\BaseObject
init() 初始化该动作. yii\captcha\CaptchaAction
off() 从该组件分离现有的事件处理程序. yii\base\Component
on() 将事件处理程序附加到事件. yii\base\Component
run() 运行该动作. yii\captcha\CaptchaAction
runWithParams() 使用指定的参数运行此动作. yii\base\Action
trigger() 触发事件. yii\base\Component
validate() 验证输入以查看它是否与生成的代码匹配. yii\captcha\CaptchaAction

受保护的方法

隐藏继承的方法

方法描述定义在
afterRun() 在执行run()之后立即调用此方法. yii\base\Action
beforeRun() 在执行run()之前立即调用此方法. yii\base\Action
generateVerifyCode() 生成一个新的验证码. yii\captcha\CaptchaAction
getSessionKey() 返回用于存储验证码的会话(session)变量名称. yii\captcha\CaptchaAction
renderImage() 渲染验证码(CAPTCHA)图像. yii\captcha\CaptchaAction
renderImageByGD() 使用 GD 库基于代码渲染验证码(CAPTCHA)图像. yii\captcha\CaptchaAction
renderImageByImagick() 使用 ImageMagick 库基于代码渲染验证码(CAPTCHA)图像. yii\captcha\CaptchaAction
setHttpHeaders() 设置图像响应所需的 HTTP 标头. yii\captcha\CaptchaAction

常量

隐藏继承的常量

常量描述定义在
REFRESH_GET_VAR 'refresh' GET 参数的名称, 指示是否应该重新生成验证码(CAPTCHA)图像. yii\captcha\CaptchaAction

属性详情

$backColor public 属性

背景颜色. 默认为0xFFFFFF(白色).

public integer $backColor 0xFFFFFF
$fixedVerifyCode public 属性

固定的验证码.

当设置此属性时, getVerifyCode() 将始终返回此属性的值.

这主要用于自动化测试, 我们希望每次运行测试时都能重现相同的验证码.

如果未设置, 则表示将被随机生成验证码.

public string $fixedVerifyCode null
$fontFile public 属性

TrueType 字体文件. 这可以是文件路径或 路径别名.

public string $fontFile '@yii/captcha/SpicyRice.ttf'
$foreColor public 属性

字体颜色. 默认为0x2040A0(蓝色).

public integer $foreColor 0x2040A0
$height public 属性

生成的验证码(CAPTCHA)图像的高度. 默认为50.

public integer $height 50
$imageLibrary public 属性 (可用自版本: 2.0.7)

要使用的渲染库.

目前仅支持gdimagick.

如果未设置, 将自动确定库.

public string $imageLibrary null
$maxLength public 属性

随机生成的单词的最大长度. 默认为7.

public integer $maxLength 7
$minLength public 属性

随机生成的单词的最小长度. 默认为6.

public integer $minLength 6
$offset public 属性

字符之间的偏移量. 默认为-2.

你可以调整此属性以降低或提高验证码的可读性.

public integer $offset = -2
$padding public 属性

在文本周围的填充. 默认为2.

public integer $padding 2
$testLimit public 属性

应该显示相同验证码(CAPTCHA)的次数. 默认为3.

小于或等于0的值表示次数是无限制的(自版本 1.1.2 起可用).

public integer $testLimit 3
$transparent public 属性

是否使用透明背景. 默认为false.

public boolean $transparent false
$verifyCode public 属性

验证码. 该属性是只读的.

public string $verifyCode null
$width public 属性

生成的验证码(CAPTCHA)图像的宽度. 默认为120.

public integer $width 120

方法详情

generateValidationHash() public 方法

生成可用于客户端验证的哈希码.

public string generateValidationHash ( $code )
$code string

验证码(CAPTCHA).

return string

从验证码(CAPTCHA)生成的哈希码.

generateVerifyCode() protected 方法

生成一个新的验证码.

protected string generateVerifyCode ( )
return string

生成的验证码.

getSessionKey() protected 方法

返回用于存储验证码的会话(session)变量名称.

protected string getSessionKey ( )
return string

会话(session)变量名称.

getVerifyCode() public 方法

获取验证码.

public string getVerifyCode ( $regenerate false )
$regenerate boolean

是否应该重新生成验证码.

return string

验证码.

init() public 方法

初始化该动作.

public void init ( )
throws yii\base\InvalidConfigException

如果字体文件不存在.

renderImage() protected 方法

渲染验证码(CAPTCHA)图像.

protected string renderImage ( $code )
$code string

验证码.

return string

图像内容.

throws yii\base\InvalidConfigException

如果不支持 imageLibrary.

renderImageByGD() protected 方法

使用 GD 库基于代码渲染验证码(CAPTCHA)图像.

protected string renderImageByGD ( $code )
$code string

验证码.

return string

PNG 格式的图像内容.

renderImageByImagick() protected 方法

使用 ImageMagick 库基于代码渲染验证码(CAPTCHA)图像.

protected string renderImageByImagick ( $code )
$code string

验证码.

return string

PNG 格式的图像内容.

run() public 方法

运行该动作.

public void run ( )
setHttpHeaders() protected 方法

设置图像响应所需的 HTTP 标头.

protected void setHttpHeaders ( )
validate() public 方法

验证输入以查看它是否与生成的代码匹配.

public boolean validate ( $input, $caseSensitive )
$input string

用户输入.

$caseSensitive boolean

比较是否应区分大小写.

return boolean

输入是否有效.