This plugin aims to ship with robust and most importantly "user-friendly" captchas. There is nothing more annoying as captcha images you can't make out the content for 5+ trials.

It is also not supposed to replace the Security/Csrf components and bot-protection mechanisms. More likely one would use them side by side.

Simple math captchas are also usually a bit more fun than trying to figure out some unreadable words behind colorful bars. But since this plugin ships with a highly extensible interface solution, you can write and use your own captcha image solution.

The behavior controls stored state; the engine controls the visible challenge.

Both Captcha configurations can include PassiveCaptcha. The public behavior names remain unchanged. See database-backed captchas and honeypots for setup.

For an invisible form with a stored token, configure Captcha.engine as \Captcha\Engine\NullEngine::class and attach Captcha.Captcha. Render it with the same helper as other database-backed captchas. Add Captcha.PassiveCaptcha for honeypot checks, and explicitly enable its limiter to count those failures.

For monitoring captcha health and investigating abuse, the plugin ships with a self-contained admin backend:

• Admin: Setup, routing, auth, and feature reference

Using the default MathEngine we can simply attach the behavior to the Table class.

Load the helper, e.g in your AppView:

$this->loadHelper('Captcha.Captcha');

Add a captcha control (active + passive) in your form:

echo $this->Captcha->render(['placeholder' => __('Please solve the riddle')]);

Add the behavior at runtime in your controller action:

$this->Ads->addBehavior('Captcha.Captcha');

If you want to also use the passive one, also add:

$this->Ads->addBehavior('Captcha.PassiveCaptcha');

Saving a new ad would now require a valid captcha solution.

// This would come from the form POST
$postData = [
    'title' => 'Looking for a friend',
];

$ad = $this->Ads->newEntity($postData);
$success = $this->Ads->save($ad);

For detailed documentation see the above docs on active and passive ones.

I usually like to secure any public form with a captcha. But only for visitors that are not logged in. So once someone is, the captcha security is usually not needed anymore.

Using TinyAuth or session directly:

// in controller
if (PHP_SAPI !== 'cli' && !$this->AuthUser->id()) {
    $this->loadComponent('Captcha.Captcha');
}

// in template
if (PHP_SAPI !== 'cli' && !$this->AuthUser->id()) {
    echo $this->Captcha->render();
}

Note: The PHP_SAPI check can be helpful to keep this out of the unit testing. So the controller test will be simpler and you don't have to mock around the captcha validation here.