BotDetect CakePHP 3.0 CAPTCHA Integration Quickstart (BotDetect v3.0; deprecated)

1. Installing the BotDetect CakePHP Captcha Composer Plugin

Path Aliases Used Throughout This Guide

  • <MY_CAKE_WEBROOT>: the root of the application install (same as the ROOT PHP CakePHP constant)
  • <BD_CAKE_PACK>: the downloaded and extracted contents of the BotDetect Captcha CakePHP Package

Note: If you do not have Composer yet, you can install it by following the instructions on

If you have Git installed on your development machine, you should use the following installation procedure:

Step 1: Install the BotDetect CakePHP Captcha Composer Plugin:

Run the following command in your application's root directory:

Step 2: Load the BotDetect CakePHP Captcha Composer Plugin in your application's bootstrap (<MY_CAKE_WEBROOT>/config/bootstrap.php):

Plugin::load('CakeCaptcha', ['routes' => true]);

2. Show a Captcha Challenge on the Form

Create an instance of the Captcha class and generate a Captcha markup in your Controller:
<?php namespace App\Controller;

use App\Controller\AppController;
// Importing the BotDetectCaptcha class
use CakeCaptcha\Integration\BotDetectCaptcha;

class ExampleController extends AppController
    // get captcha instance to handle for the example page
    private function getExampleCaptchaInstance() {
        // Captcha parameters
        $captchaConfig = [
          'CaptchaId' => 'ExampleCaptcha', // a unique Id for the Captcha instance
          'UserInputId' => 'CaptchaCode', // Id of the Captcha code input textbox
          // The path of the Captcha config file is inside the config folder
          'CaptchaConfigFilePath' => 'captcha_config/ExampleCaptchaConfig.php', 
        return BotDetectCaptcha::GetCaptchaInstance($captchaConfig);

    public function index() {
        // captcha instance of the example page
        $captcha = $this->getExampleCaptchaInstance();

        // passing Captcha Html to example view
        $this->set('captchaHtml', $captcha->Html());

Captcha configuration options (/config/captcha_config/ExampleCaptchaConfig.php):

<?php if (!class_exists('CaptchaConfiguration')) { return; }

// BotDetect PHP Captcha configuration options

$LBD_CaptchaConfig = CaptchaConfiguration::GetSettings();

$LBD_CaptchaConfig->CodeLength = 5;
$LBD_CaptchaConfig->ImageWidth = 250;
$LBD_CaptchaConfig->ImageHeight = 50;

Showing a Captcha challenge in a View:

<!-- include the BotDetect layout stylesheet -->
<?= $this->Html->css(CaptchaUrls::LayoutStylesheetUrl(), array('inline' => false)) ?>

  <!-- show captcha image -->
  <?= $captchaHtml ?>

  <!-- Captcha code user input textbox -->
  <?= $this->Form->input('CaptchaCode', array(
          'id' => 'CaptchaCode'
  ) ?>

3. Check User Input During Form Submission

When a form is submitted, Captcha validation result must be checked in a Controller code:
// captcha instance of the example page
$captcha = $this->getExampleCaptchaInstance();

if ($this->request->is('post')) {

    // validate the user-entered Captcha code
    $isHuman = $captcha->Validate($this->request->data['CaptchaCode']);

    unset($this->request->data['CaptchaCode']); // clear previous user input

    if ($isHuman) {
      // TODO: Captcha validation passed, perform protected action
    } else {
      // TODO: Captcha validation failed, show error message

In-Depth CakePHP CAPTCHA Instructions and Explanations

Detailed CakePHP Captcha instructions and explanations can be found in the CakePHP 3.0 Captcha integration how to guide.

Other BotDetect PHP CAPTCHA Quickstarts

CodeIgniter 3.0 CAPTCHA Laravel 5.0 CAPTCHA  
CodeIgniter 2.2 CAPTCHA Laravel 4.2 CAPTCHA  

Please Note

The information on this page is out of date and applies to a deprecated version of BotDetect™ CAPTCHA (v3.0).

An up-to-date equivalent page for the latest BotDetect Captcha release (v4) is BotDetect v4 Captcha documentation index.

General information about the major improvements in the current BotDetect release can be found at the What's New in BotDetect v4.0 page.