CaptchaAction

API reference › yii › captcha › CaptchaAction

class	`yii\captcha\CaptchaAction`
Extends	`yii\base\Action` » `yii\base\Component` » `yii\base\BaseObject`
Implements	`yii\base\Configurable`
Since	2.0
Source	`framework/captcha/CaptchaAction.php`

CaptchaAction renders a CAPTCHA image.

CaptchaAction is used together with Captcha and CaptchaValidator to provide the CAPTCHA feature.

By configuring the properties of CaptchaAction, you may customize the appearance of the generated CAPTCHA images, such as the font color, the background color, etc.

Note that CaptchaAction requires either GD2 extension or ImageMagick PHP extension.

Using CAPTCHA involves the following steps:

Override Controller::actions() and register an action of class CaptchaAction with ID ‘captcha’
In the form model, declare an attribute to store user-entered verification code, and declare the attribute to be validated by the ‘captcha’ validator.
In the controller view, insert a Captcha widget in the form.

Properties

Property	Type	Description	Defined by
`$backColor`	`int`	The background color. Default: `0xffffff`.	`CaptchaAction`
`$behaviors` read-only	`array<yii\base\Behavior<static>>`	List of behaviors attached to this component.	`yii\base\Component`
`$controller`	`yii\base\T\|null`	The controller that owns this action, or `null` when the action runs standalone. via `Module::$actionMap` Default: `null`.	`yii\base\Action`
`$fixedVerifyCode`	`string\|null`	The fixed verification code. Default: `null`.	`CaptchaAction`
`$fontFile`	`string`	The TrueType font file. Default: `'@yii/captcha/SpicyRice.ttf'`.	`CaptchaAction`
`$foreColor`	`int`	The font color. Default: `0x2040a0`.	`CaptchaAction`
`$height`	`int`	The height of the generated CAPTCHA image. Default: `50`.	`CaptchaAction`
`$id`	`string\|null`	ID of the action; `null` between construction and dispatcher post-assignment for standalone actions resolved through `Module::$actionMap` or `Module::$actionNamespace`. Default: `null`.	`yii\base\Action`
`$imageLibrary`	`string\|null`	The rendering library to use. Default: `null`. Available since 2.0.7.	`CaptchaAction`
`$maxLength`	`int`	The maximum length for randomly generated word. Default: `7`.	`CaptchaAction`
`$minLength`	`int`	The minimum length for randomly generated word. Default: `6`.	`CaptchaAction`
`$module`	`yii\base\Module\|null`	The owning module, or `null` if neither a module nor a controller is attached. Available since 22.0.	`yii\base\Action`
`$offset`	`int`	The offset between characters. Default: `-2`.	`CaptchaAction`
`$padding`	`int`	Padding around the text. Default: `2`.	`CaptchaAction`
`$testLimit`	`int`	How many times should the same CAPTCHA be displayed. Default: `3`.	`CaptchaAction`
`$transparent`	`bool`	Whether to use transparent background. Default: `false`.	`CaptchaAction`
`$uniqueId` read-only	`string`	The unique ID of this action among the whole application.	`yii\base\Action`
`$verifyCode` read-only	`string`	The verification code.	`CaptchaAction`
`$width`	`int`	The width of the generated CAPTCHA image. Default: `120`.	`CaptchaAction`

Methods

Method	Description	Defined by
`__construct()`	Constructor.	`yii\base\Action`
`__call()`	Calls the named method which is not a class method.	`yii\base\Component`
`__clone()`	This method is called after the object is created by cloning an existing one.	`yii\base\Component`
`__get()`	Returns the value of a component property.	`yii\base\Component`
`__isset()`	Checks if a property is set, i.e. defined and not null.	`yii\base\Component`
`__set()`	Sets the value of a component property.	`yii\base\Component`
`__unset()`	Sets a component property to be null.	`yii\base\Component`
`attachBehavior()`	Attaches a behavior to this component.	`yii\base\Component`
`attachBehaviors()`	Attaches a list of behaviors to the component.	`yii\base\Component`
`behaviors()`	Returns a list of behaviors that this component should behave as.	`yii\base\Component`
`canGetProperty()`	Returns a value indicating whether a property can be read.	`yii\base\Component`
`canSetProperty()`	Returns a value indicating whether a property can be set.	`yii\base\Component`
`className()` static	Returns the fully qualified name of this class.	`yii\base\BaseObject`
`detachBehavior()`	Detaches a behavior from the component.	`yii\base\Component`
`detachBehaviors()`	Detaches all behaviors from the component.	`yii\base\Component`
`ensureBehaviors()`	Makes sure that the behaviors declared in `behaviors()` are attached to this component.	`yii\base\Component`
`generateValidationHash()`	Generates a hash code that can be used for client-side validation.	`CaptchaAction`
`getBehavior()`	Returns the named behavior object.	`yii\base\Component`
`getBehaviors()`	Returns all behaviors attached to this component.	`yii\base\Component`
`getModule()`	Returns the module that owns this action when invoked standalone.	`yii\base\Action`
`getUniqueId()`	Returns the unique ID of this action among the whole application.	`yii\base\Action`
`getVerifyCode()`	Gets the verification code.	`CaptchaAction`
`hasEventHandlers()`	Returns a value indicating whether there is any handler attached to the named event.	`yii\base\Component`
`hasMethod()`	Returns a value indicating whether a method is defined.	`yii\base\Component`
`hasProperty()`	Returns a value indicating whether a property is defined for this component.	`yii\base\Component`
`init()`	Initializes the action.	`CaptchaAction`
`off()`	Detaches an existing event handler from this component.	`yii\base\Component`
`on()`	Attaches an event handler to an event.	`yii\base\Component`
`run()`	Runs the action.	`CaptchaAction`
`runWithParams()`	Runs this action with the specified parameters.	`yii\base\Action`
`setModule()`	Sets the module that owns this action when invoked standalone.	`yii\base\Action`
`trigger()`	Triggers an event.	`yii\base\Component`
`validate()`	Validates the input to see if it matches the generated code.	`CaptchaAction`
`afterRun()` protected	This method is called right after `run()` is executed.	`yii\base\Action`
`beforeRun()` protected	This method is called right before `run()` is executed.	`yii\base\Action`
`generateVerifyCode()` protected	Generates a new verification code.	`CaptchaAction`
`getSessionKey()` protected	Returns the session variable name used to store verification code.	`CaptchaAction`
`renderImage()` protected	Renders the CAPTCHA image.	`CaptchaAction`
`renderImageByGD()` protected	Renders the CAPTCHA image based on the code using GD library.	`CaptchaAction`
`renderImageByImagick()` protected	Renders the CAPTCHA image based on the code using ImageMagick library.	`CaptchaAction`
`resolveStandaloneParams()` protected	Resolves typed parameters of `run()` when the action is invoked without a hosting controller.	`yii\base\Action`
`setHttpHeaders()` protected	Sets the HTTP headers needed by image response.	`CaptchaAction`

Constants

Constant	Value	Description	Defined by
`REFRESH_GET_VAR`	`'refresh'`	The name of the GET parameter indicating whether the CAPTCHA image should be regenerated.	`CaptchaAction`

Property details

$backColor

public int $backColor = 0xffffff

The background color.

For example, 0x55FF00. Defaults to 0xFFFFFF, meaning white color.

$fixedVerifyCode

public string|null $fixedVerifyCode = null

The fixed verification code.

When this property is set, getVerifyCode() will always return the value of this property. This is mainly used in automated tests where we want to be able to reproduce the same verification code each time we run the tests. If not set, it means the verification code will be randomly generated.

$fontFile

public string $fontFile = '@yii/captcha/SpicyRice.ttf'

The TrueType font file.

This can be either a file path or path alias.

$foreColor

public int $foreColor = 0x2040a0

The font color.

For example, 0x55FF00. Defaults to 0x2040A0 (blue color).

$height

public int $height = 50

The height of the generated CAPTCHA image.

Defaults to 50.

$imageLibrary

public string|null $imageLibrary = null

The rendering library to use.

Currently supported only ‘gd’ and ‘imagick’. If not set, library will be determined automatically.

Since

2.0.7

$maxLength

public int $maxLength = 7

The maximum length for randomly generated word.

Defaults to 7.

$minLength

public int $minLength = 6

The minimum length for randomly generated word.

Defaults to 6.

$offset

public int $offset = -2

The offset between characters.

Defaults to -2. You can adjust this property in order to decrease or increase the readability of the captcha.

$padding

public int $padding = 2

Padding around the text.

Defaults to 2.

$testLimit

public int $testLimit = 3

How many times should the same CAPTCHA be displayed.

Defaults to 3. A value less than or equal to 0 means the test is unlimited (available since version 1.1.2).

$transparent

public bool $transparent = false

Whether to use transparent background.

Defaults to false.

$width

public int $width = 120

The width of the generated CAPTCHA image.

Defaults to 120.

Method details

generateValidationHash()

public function generateValidationHash(string $code): int

Generates a hash code that can be used for client-side validation.

Parameters

Parameter	Type	Description
`$code`	`string`	The CAPTCHA code

Returns

int: A hash code generated from the CAPTCHA code

getVerifyCode()

public function getVerifyCode(bool $regenerate = false): string

Gets the verification code.

Parameters

Parameter	Type	Description
`$regenerate`	`bool`	Whether the verification code should be regenerated.

Returns

string: The verification code.

init()

public function init(): mixed

Initializes the action.

Returns

mixed

Throws

yii\base\InvalidConfigException: if the font file does not exist.

run()

public function run(): mixed

Runs the action.

Returns

mixed

validate()

public function validate(string $input, bool $caseSensitive): bool

Validates the input to see if it matches the generated code.

Parameters

Parameter	Type	Description
`$input`	`string`	User input
`$caseSensitive`	`bool`	Whether the comparison should be case-sensitive

Returns

bool: Whether the input is valid

generateVerifyCode()

protected function generateVerifyCode(): string

Generates a new verification code.

Returns

string: The generated verification code

getSessionKey()

protected function getSessionKey(): string

Returns the session variable name used to store verification code.

Returns

string: The session variable name

renderImage()

protected function renderImage(string $code): string

Renders the CAPTCHA image.

Parameters

Parameter	Type	Description
`$code`	`string`	The verification code

Returns

string: Image contents

Throws

yii\base\InvalidConfigException: if imageLibrary is not supported

renderImageByGD()

protected function renderImageByGD(string $code): string

Renders the CAPTCHA image based on the code using GD library.

Parameters

Parameter	Type	Description
`$code`	`string`	The verification code

Returns

string: Image contents in PNG format.

renderImageByImagick()

protected function renderImageByImagick(string $code): string

Renders the CAPTCHA image based on the code using ImageMagick library.

Parameters

Parameter	Type	Description
`$code`	`string`	The verification code

Returns

string: Image contents in PNG format.

setHttpHeaders()

protected function setHttpHeaders(): mixed

Sets the HTTP headers needed by image response.

Returns

mixed