To add CAPTCHA to forms in Yii, first enable the CAPTCHA action in your controller by defining it in the actions() method, which creates a dynamic route for generating the CAPTCHA image. Second, create a verifyCode attribute in your form model and apply the captcha validation rule to it. Third, display the CAPTCHA in your form view using the Captcha widget with a custom template and correct captchaAction path. Finally, during form submission, Yii automatically validates the CAPTCHA input as long as the model’s validate() method is called, ensuring the entered code matches the generated one. Common issues include incorrect session setup or caching pages with CAPTCHA, which should be avoided.

Adding CAPTCHA to forms in Yii is a straightforward way to prevent bots from submitting your forms. It involves setting up both the front-end display and the back-end validation, and Yii provides built-in support for this.

1. Enable CAPTCHA in Your Controller

Before displaying the CAPTCHA on a form, you need to configure it in your controller. This is done by declaring a captcha action in the controller where your form is being handled.

public function actions()
{
    return [
        'captcha' => [
            'class' => 'yii\captcha\CaptchaAction',
            'fixedVerifyCode' => YII_ENV_TEST ? 'testme' : null,
        ],
    ];
}

This sets up a route like /your-controller/captcha that will generate the CAPTCHA image dynamically. The fixedVerifyCode line helps during testing so you can bypass manual CAPTCHA entry.

2. Add CAPTCHA Field to Your Form Model

You’ll need to create a field in your model (usually a form model) to hold the user’s CAPTCHA input. This field should be validated using the captcha validator.

public $verifyCode;

public function rules()
{
    return [
        // other rules...
        ['verifyCode', 'captcha'],
    ];
}

Make sure your model extends yii\base\Model or one of its subclasses.

3. Display CAPTCHA in the Form View

In your view file, use the Captcha widget to render the CAPTCHA image and input field.

<?= $form->field($model, 'verifyCode')->widget(yii\captcha\Captcha::className(), [
    'captchaAction' => '/controller/captcha',
    'template' => '<div class="row"><div class="col-lg-3">{image}</div><div class="col-lg-6">{input}</div></div>',
]) ?>

Here:

• captchaAction points to the CAPTCHA action you set up earlier.
• template allows you to customize how the CAPTCHA image and input box are displayed together.

Tip: If you're using Bootstrap, wrapping them in grid columns like shown above keeps the layout clean.

4. Handle Validation During Form Submission

When the form is submitted, the captcha rule in your model ensures the entered code matches the generated one. If not, an error message will automatically appear next to the CAPTCHA field.

No extra code is needed in your controller action that handles the form submission — just make sure you call $model->validate() or let Yii handle it via ActiveForm.

Some Common Issues to Watch For

• CAPTCHA not showing: Make sure the captcha action is properly defined in the controller.
• Validation always fails: Double-check that the session component is working — CAPTCHA relies on sessions to store the correct code.
• Caching issues: If you're using page caching, avoid caching pages with CAPTCHA since each CAPTCHA must be unique per session.

That's basically it. It doesn’t require much setup, but it adds a solid layer of protection against spam and bot submissions.

The above is the detailed content of How do I use CAPTCHA in Yii forms?. For more information, please follow other related articles on the PHP Chinese website!