# CaptchaAction

> CaptchaAction renders a CAPTCHA image.

[API reference](/docs/api/index.md) › [yii](/docs/api/yii/index.md) › [captcha](/docs/api/yii/captcha/index.md) › CaptchaAction

| class | `yii\captcha\CaptchaAction` |
| --- | --- |
| Extends | [`yii\base\Action`](/docs/api/yii/base/action/index.md) » [`yii\base\Component`](/docs/api/yii/base/component/index.md) » [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| Implements | [`yii\base\Configurable`](/docs/api/yii/base/configurable/index.md) |
| Since | 2.0 |
| Source | [`framework/captcha/CaptchaAction.php`](https://github.com/yiisoft/yii2/blob/22.0/framework/captcha/CaptchaAction.php#L44) |

CaptchaAction renders a CAPTCHA image.

CaptchaAction is used together with [`Captcha`](/docs/api/yii/captcha/captcha/index.md) and [`CaptchaValidator`](/docs/api/yii/captcha/captchavalidator/index.md)
to provide the [CAPTCHA](https://en.wikipedia.org/wiki/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:

1. Override [`Controller::actions()`](/docs/api/yii/base/controller/index.md#method-actions) and register an action of class CaptchaAction with ID 'captcha'
2. In the form model, declare an attribute to store user-entered verification code, and declare the attribute
   to be validated by the 'captcha' validator.
3. In the controller view, insert a [`Captcha`](/docs/api/yii/captcha/captcha/index.md) widget in the form.

## Properties

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

## Methods

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

## Constants

| Constant | Value | Description | Defined by |
| --- | --- | --- | --- |
| <span id="const-REFRESH_GET_VAR"></span>`REFRESH_GET_VAR` | `'refresh'` | The name of the GET parameter indicating whether the CAPTCHA image should be regenerated. | `CaptchaAction` |

## Property details

### $backColor <span id="property-backColor"></span>

```php
public int $backColor = 0xffffff
```

The background color.

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

### $fixedVerifyCode <span id="property-fixedVerifyCode"></span>

```php
public string|null $fixedVerifyCode = null
```

The fixed verification code.

When this property is set,
[`getVerifyCode()`](/docs/api/yii/captcha/captchaaction/index.md#method-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 <span id="property-fontFile"></span>

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

The TrueType font file.

This can be either a file path or [path alias](/docs/guide/concept-aliases/index.md).

### $foreColor <span id="property-foreColor"></span>

```php
public int $foreColor = 0x2040a0
```

The font color.

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

### $height <span id="property-height"></span>

```php
public int $height = 50
```

The height of the generated CAPTCHA image.

Defaults to 50.

### $imageLibrary <span id="property-imageLibrary"></span>

```php
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 <span id="property-maxLength"></span>

```php
public int $maxLength = 7
```

The maximum length for randomly generated word.

Defaults to 7.

### $minLength <span id="property-minLength"></span>

```php
public int $minLength = 6
```

The minimum length for randomly generated word.

Defaults to 6.

### $offset <span id="property-offset"></span>

```php
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 <span id="property-padding"></span>

```php
public int $padding = 2
```

Padding around the text.

Defaults to 2.

### $testLimit <span id="property-testLimit"></span>

```php
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 <span id="property-transparent"></span>

```php
public bool $transparent = false
```

Whether to use transparent background.

Defaults to false.

### $width <span id="property-width"></span>

```php
public int $width = 120
```

The width of the generated CAPTCHA image.

Defaults to 120.

## Method details

### generateValidationHash() <span id="method-generateValidationHash"></span>

```php
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() <span id="method-getVerifyCode"></span>

```php
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() <span id="method-init"></span>

```php
public function init(): mixed
```

Initializes the action.

**Returns**

`mixed`

**Throws**

- [`yii\base\InvalidConfigException`](/docs/api/yii/base/invalidconfigexception/index.md): if the font file does not exist.

### run() <span id="method-run"></span>

```php
public function run(): mixed
```

Runs the action.

**Returns**

`mixed`

### validate() <span id="method-validate"></span>

```php
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() <span id="method-generateVerifyCode"></span>

```php
protected function generateVerifyCode(): string
```

Generates a new verification code.

**Returns**

`string`: The generated verification code

### getSessionKey() <span id="method-getSessionKey"></span>

```php
protected function getSessionKey(): string
```

Returns the session variable name used to store verification code.

**Returns**

`string`: The session variable name

### renderImage() <span id="method-renderImage"></span>

```php
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`](/docs/api/yii/base/invalidconfigexception/index.md): if imageLibrary is not supported

### renderImageByGD() <span id="method-renderImageByGD"></span>

```php
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() <span id="method-renderImageByImagick"></span>

```php
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() <span id="method-setHttpHeaders"></span>

```php
protected function setHttpHeaders(): mixed
```

Sets the HTTP headers needed by image response.

**Returns**

`mixed`