BotDetect CakePHP 3 CAPTCHA Integration Quickstart

Unlike Recaptcha the Stalker -- BotDetect CAPTCHA works in China! Licensable source-code; self-hosted -- doesn't stalk -- nor does it slurp your form-data! Think: GDPR & LGPD!

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

a) If CakePHP is a backend for your js-based frontend, perhaps you should start with a guide that describes integration from js-framework point of view: jQuery, Angular, AngularJS, or React.

b) If you are using CakePHP forms, here is how to configure Captcha options, and display Captcha in your CakePHP form:

Captcha configuration options (/config/captcha.php):

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

// BotDetect PHP Captcha configuration options

return [
  // Captcha configuration for example page
  'ExampleCaptcha' => [
    'UserInputID' => 'CaptchaCode',
    'ImageWidth' => 250,
    'ImageHeight' => 50,
Load the BotDetect CakePHP component:
<?php namespace App\Controller;

use App\Controller\AppController;

class ExampleController extends AppController
  public function initialize()

    // load the Captcha component and set its parameter
    $this->loadComponent('CakeCaptcha.Captcha', [
      'captchaConfig' => 'ExampleCaptcha'

Showing a Captcha challenge in a View:

<!-- include the BotDetect layout stylesheet -->
<?= $this->Html->css(captcha_layout_stylesheet_url(), ['inline' => false]) ?>

  <!-- show captcha image -->
  <?= captcha_image_html() ?>

  <!-- Captcha code user input textbox -->
  <?= $this->Form->input('CaptchaCode', [
    'label' => 'Retype the characters from the picture:',
    'maxlength' => '10',
    'style' => 'width: 270px;',
    'id' => 'CaptchaCode'
  ]) ?>

3. Check User Input During Form Submission

When a form is submitted, Captcha validation result must be checked in a Controller code:
if ($this->request->is('post')) {

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

  // clear previous user input, since each Captcha code can only be validated once
  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 Captcha integration how to guide.

Other BotDetect PHP CAPTCHA Quickstarts

CodeIgniter CAPTCHA

BotDetect CakePHP CAPTCHA System Requirements


Supported CakePHP Versions:

  • CakePHP 3.x