CakePHP 3 Basic BotDetect CAPTCHA Example

This code example illustrates the most basic form of BotDetect PHP Captcha protection in CakePHP MVC applications.

Alongside the Captcha image, the user is provided with an input field to retype the displayed characters. Depending on if the Captcha code entered matches the displayed one or not, a message stating the validation result is shown on the form.

The simple code showing the message in this example would of course be replaced with useful form processing code in a real world scenario.

Files for this ('bd-captcha-cakephp-3-examples') example are:

• /config/captcha.php
• /src/Template/Example/index.ctp
• /src/Controller/ExampleController.php

The files are available for download as a part of the BotDetect Captcha CakePHP integration package.

Config – /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,
  ],
  
];

In order to use the CakePHP CAPTCHA Plugin, we have declared Captcha configuration which will be used when loading Captcha component in ExampleController. Detailed description of this approach is available in a BotDetect CakePHP 3 integration guide.

View – /src/Template/Example/index.ctp

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

<div class="users form">
  <?= $this->Form->create(null, ['action' => 'index']) ?>

   <fieldset>
    <legend><?= __('CakePHP Basic BotDetect CAPTCHA Example') ?></legend>

    <!-- show captcha image html -->
    <?= 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'
    ]) ?>

   </fieldset>

  <?= $this->Form->button(__('Submit'), ['style' => 'float: left; margin-left: 20px;']) ?>
  <?= $this->Form->end() ?>
</div>

The above code uses the CakePHP FormHelper to generate a form, although the actual form can be created in many other ways. The only requirement is that the form contains an input field of your choice where the user can retype the characters shown in the Captcha image. This user-entered code should be available to you in Controller code after form submission.

Note that the action of the form points to the same action of the Controller the View belongs to. Also, the name of the input field corresponds to the variable in the request object that we will use for validation in the Controller.

We display the image by calling the captcha_image_html() helper function. The View utilizes the HtmlHelper::css() method to add the required stylesheet, and it also prints out a message about the Captcha validation status (set in the Controller).

[back to the top of the page]

Controller – /src/Controller/ExampleController.php

<?php namespace App\Controller;

use Cake\Controller\Controller;

class ExampleController extends Controller
{
  public function initialize()
  {
    parent::initialize();

    $this->loadComponent('Flash');

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

  public function index() 
  {
    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) {
        // Captcha validation passed
        $this->Flash->success(__('CAPTCHA validation passed, human visitor confirmed!'));
        // TODO: continue with form processing, knowing the submission was made by a human
      } else {
        // Captcha validation failed, return an error message
        $this->Flash->error(__('CAPTCHA validation failed, please try again.'));
      }
    }
  }
}

The example Controller follows the basic instructions from the BotDetect CakePHP 3 integration guide.

After loading the BotDetect Captcha CakePHP component, the example form submits the data to the same Controller action that shows it (index), which is where we check the submitted data and pass it to the captcha_validate() helper function.

[back to the top of the page]