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 https://getcomposer.org

With local Git (Default)
Without local Git

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]);

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

Step 1: Open composer.json file from your application's root directory and add the repository (<MY_CAKE_WEBROOT>/composer.json):

{
  "repositories": [
    {
      "type": "composer",
      "url": "http://packages.captcha.com"
    }
  ]
}

Step 2: Install the BotDetect CakePHP Captcha Composer Plugin:

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

Step 3: 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()
  {
    parent::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]) ?>
</head>
  
  [...]

  <!-- 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
  unset($this->request->data['CaptchaCode']);
 
  if ($isHuman) {
      // TODO: Captcha validation passed, perform protected action
  } else {
      // TODO: Captcha validation failed, show error message
  }
}