Class yii\captcha\Captcha
| Inheritance | yii\captcha\Captcha » yii\widgets\InputWidget » yii\base\Widget » yii\base\Component » yii\base\BaseObject |
|---|---|
| Implements | yii\base\Configurable, yii\base\ViewContextInterface |
| Available since version | 2.0 |
| Source Code | https://github.com/yiisoft/yii2/blob/master/framework/captcha/Captcha.php |
Captcha renders a CAPTCHA image and an input field that takes user-entered verification code.
Captcha is used together with yii\captcha\CaptchaAction to provide CAPTCHA - a way of preventing website spamming.
The image element rendered by Captcha will display a CAPTCHA image generated by an action whose route is specified by $captchaAction. This action must be an instance of yii\captcha\CaptchaAction.
When the user clicks on the CAPTCHA image, it will cause the CAPTCHA image to be refreshed with a new CAPTCHA.
You may use yii\captcha\CaptchaValidator to validate the user input matches the current CAPTCHA verification code.
The following example shows how to use this widget with a model attribute:
echo Captcha::widget([
'model' => $model,
'attribute' => 'captcha',
]);
The following example will use the name property instead:
echo Captcha::widget([
'name' => 'captcha',
]);
You can also use this widget in an ActiveForm using the widget() method, for example like this:
<?= $form->field($model, 'captcha')->widget(\yii\captcha\Captcha::classname(), [
// configure additional widget properties here
]) ?>
Public Properties
| Property | Type | Description | Defined By |
|---|---|---|---|
| $attribute | string | The model attribute that this widget is associated with. | yii\widgets\InputWidget |
| $autoIdPrefix | string | The prefix to the automatically generated widget IDs. | yii\base\Widget |
| $captchaAction | string|array | The route of the action that generates the CAPTCHA images. | yii\captcha\Captcha |
| $counter | integer | A counter used to generate \yii\base\id for widgets. | yii\base\Widget |
| $field | yii\widgets\ActiveField | Active input field, which triggers this widget rendering. | yii\widgets\InputWidget |
| $imageOptions | array | HTML attributes to be applied to the CAPTCHA image tag. | yii\captcha\Captcha |
| $model | yii\base\Model | The data model that this widget is associated with. | yii\widgets\InputWidget |
| $name | string | The input name. | yii\widgets\InputWidget |
| $options | array | The HTML attributes for the input tag. | yii\captcha\Captcha |
| $stack | yii\base\Widget[] | The widgets that are currently being rendered (not ended). | yii\base\Widget |
| $template | string | The template for arranging the CAPTCHA image tag and the text input tag. | yii\captcha\Captcha |
| $value | string | The input value. | yii\widgets\InputWidget |
Public Methods
| Method | Description | Defined By |
|---|---|---|
| __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 |
| __construct() | Constructor. | yii\base\BaseObject |
| __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 |
| afterRun() | This method is invoked right after a widget is executed. | yii\base\Widget |
| attachBehavior() | Attaches a behavior to this component. | yii\base\Component |
| attachBehaviors() | Attaches a list of behaviors to the component. | yii\base\Component |
| beforeRun() | This method is invoked right before the widget is executed. | yii\base\Widget |
| begin() | Begins a widget. | yii\base\Widget |
| 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 |
| checkRequirements() | Checks if there is graphic extension available to generate CAPTCHA images. | yii\captcha\Captcha |
| className() | 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 |
| end() | Ends a widget. | yii\base\Widget |
| ensureBehaviors() | Makes sure that the behaviors declared in behaviors() are attached to this component. | yii\base\Component |
| getBehavior() | Returns the named behavior object. | yii\base\Component |
| getBehaviors() | Returns all behaviors attached to this component. | yii\base\Component |
| getId() | Returns the ID of the widget. | yii\base\Widget |
| getView() | Returns the view object that can be used to render views or view files. | yii\base\Widget |
| getViewPath() | Returns the directory containing the view files for this widget. | yii\base\Widget |
| 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 widget. | yii\captcha\Captcha |
| off() | Detaches an existing event handler from this component. | yii\base\Component |
| on() | Attaches an event handler to an event. | yii\base\Component |
| registerClientScript() | Registers the needed JavaScript. | yii\captcha\Captcha |
| render() | Renders a view. | yii\base\Widget |
| renderFile() | Renders a view file. | yii\base\Widget |
| run() | Renders the widget. | yii\captcha\Captcha |
| setId() | Sets the ID of the widget. | yii\base\Widget |
| setView() | Sets the view object to be used by this widget. | yii\base\Widget |
| trigger() | Triggers an event. | yii\base\Component |
| widget() | Creates a widget instance and runs it. | yii\base\Widget |
Protected Methods
| Method | Description | Defined By |
|---|---|---|
| getClientOptions() | Returns the options for the captcha JS widget. | yii\captcha\Captcha |
| hasModel() | yii\widgets\InputWidget | |
| renderInputHtml() | Render a HTML input tag. | yii\widgets\InputWidget |
Events
| Event | Type | Description | Defined By |
|---|---|---|---|
| EVENT_AFTER_RUN | yii\base\WidgetEvent | An event raised right after executing a widget. (available since version 2.0.11) | yii\base\Widget |
| EVENT_BEFORE_RUN | yii\base\WidgetEvent | An event raised right before executing a widget. (available since version 2.0.11) | yii\base\Widget |
| EVENT_INIT | yii\base\Event | An event that is triggered when the widget is initialized via init(). (available since version 2.0.11) | yii\base\Widget |
Property Details
The route of the action that generates the CAPTCHA images. The action represented by this route must be an action of yii\captcha\CaptchaAction. Please refer to yii\helpers\Url::toRoute() for acceptable formats.
HTML attributes to be applied to the CAPTCHA image tag.
See also yii\helpers\Html::renderTagAttributes() for details on how attributes are being rendered.
The HTML attributes for the input tag.
See also yii\helpers\Html::renderTagAttributes() for details on how attributes are being rendered.
The template for arranging the CAPTCHA image tag and the text input tag.
In this template, the token {image} will be replaced with the actual image tag,
while {input} will be replaced with the text input tag.
Method Details
Checks if there is graphic extension available to generate CAPTCHA images.
This method will check the existence of ImageMagick and GD extensions.
| public static string checkRequirements ( ) | ||
| return | string | The name of the graphic extension, either "imagick" or "gd". |
|---|---|---|
| throws | yii\base\InvalidConfigException | if neither ImageMagick nor GD is installed. |
Returns the options for the captcha JS widget.
| protected array getClientOptions ( ) | ||
| return | array | The options |
|---|---|---|
Initializes the widget.
| public void init ( ) |
Registers the needed JavaScript.
| public void registerClientScript ( ) |
Renders the widget.
| public void run ( ) |