How to Add BotDetect PHP CAPTCHA Protection to Symfony 3 Applications

Adding BotDetect PHP Captcha protection to your Symfony MVC applications requires a slightly different approach than adding it to basic PHP websites, but is still straightforward. This page will guide you through the necessary steps and explain the available options.

First Time Here?

Check the BotDetect Symfony 3 Captcha Quickstart for key integration steps.


Table of Contents

The BotDetect Symfony CAPTCHA Integration Package

Symfony is a MVC framework that leverages certain conventions to provide a rich set of functionality to PHP application developers. Therefore adding BotDetect Captcha into Symfony based site or application requires a layer of integration code to conform to those conventions. This enables BotDetect Captcha to integrate seamlessly and be used according to expectations of Symfony developers.

Path Aliases Used Throughout This Guide

For convenience purposes we are providing the BotDetect Captcha Symfony integration code packaged as a Symfony composer package.

You can get the whole BotDetect Symfony Captcha integration package here. The package contains the integration code, basic Captcha validation example, an contact form validation example. There is also an example of adding BotDetect Captcha into FOSUserBundle Login and Register forms.

The BotDetect Symfony CaptchaBundle

BotDetect Symfony CaptchaBundle is available at

The CaptchaBundle includes a wrapper class around the regular BotDetect Captcha Library for use in your application.

The CaptchaBundle also includes separate Controllers that handle:

  • Captcha image and sound requests, which use
    http://<MY_SYMFONY_WEBROOT>/web/captcha-handler Urls by default.
  • Captcha resources request, which use
    http://<MY_SYMFONY_WEBROOT>/web/captcha-resource Urls by default.

Symfony Basic BotDetect CAPTCHA Example

This basic Symfony 3 Captcha example shows how to use the CaptchaBundle in your form, and validate user input through the ValidCaptcha constraint in your entity.

  • Config: <BD_SYMFONY_PACK>/bd-captcha-symfony3-examples /app/config/captcha.php
  • Form Type: <BD_SYMFONY_PACK>/bd-captcha-symfony3-examples/src /AppBundle/Form/Type/ExampleType.php
  • Entity: <BD_SYMFONY_PACK>/bd-captcha-symfony3-examples/src /AppBundle/Entity/Example.php
  • Controller: <BD_SYMFONY_PACK>/bd-captcha-symfony3-examples/src /AppBundle/Controllers/ExampleController.php
  • View: <BD_SYMFONY_PACK>/bd-captcha-symfony3-examples/src /AppBundle/Resources/views/Example/example.html.twig

Form Validation BotDetect Symfony CAPTCHA Example

This Symfony 3 form validation Captcha example shows how to use the CaptchaBundle in form and validate user input through the ValidCaptcha constraint in your entity by implementing a simple contact form.

  • Config: <BD_SYMFONY_PACK>/bd-captcha-symfony3-examples /app/config/captcha.php
  • Form Type: <BD_SYMFONY_PACK>/bd-captcha-symfony3-examples/src /AppBundle/Form/Type/ContactType.php
  • Entity: <BD_SYMFONY_PACK>/bd-captcha-symfony3-examples/src /AppBundle/Entity/Contact.php
  • Controller: <BD_SYMFONY_PACK>/bd-captcha-symfony3-examples/src /AppBundle/Controllers/ContactController.php
  • View: <BD_SYMFONY_PACK>/bd-captcha-symfony3-examples/src /AppBundle/Resources/views/Contact/contact.html.twig

Symfony FOSUserBundle CAPTCHA Example

This Symfony 3 FOSUserBundle CAPTCHA code example shows how to integrate CaptchaBundle into FOSUserBundle login and register forms.

  • Config: <BD_SYMFONY_PACK>/bd-captcha-symfony3-examples /app/config/captcha.php
  • Form Type: <BD_SYMFONY_PACK>/bd-captcha-symfony3-examples/src /AppBundle/Form/Type/RegistrationFormType.php
  • Entity: <BD_SYMFONY_PACK>/bd-captcha-symfony3-examples/src /AppBundle/Entity/User.php
  • View: <BD_SYMFONY_PACK>/bd-captcha-symfony3-examples/src /AppBundle/Resources/views/Security/login.html.twig
  • Controller: <BD_SYMFONY_PACK>/bd-captcha-symfony3-examples/src /AppBundle/Controllers/SecurityController.php
  • Bundle: <BD_SYMFONY_PACK>/bd-captcha-symfony3-examples/src AppBundle/AppBundle.php

Provided examples are available inside of a single Symfony app via their respective controllers:


You can copy the whole preconfigured Symfony app from the BotDetect Captcha Symfony Package somewhere on your development web server and examine it there.

1. Include BotDetect CAPTCHA in Your Symfony MVC Application

Install the BotDetect Symfony CaptchaBundle

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: Download CaptchaBundle using composer

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

Step 2: Enable the bundle (app/AppKernel.php):

$bundles = array(
  new Captcha\Bundle\CaptchaBundle\CaptchaBundle(),

Step 3: Import CaptchaBundle routing file (app/config/routing.yml):

  resource: "@CaptchaBundle/Resources/config/routing.yml"

A Note On PHP Session Persistence

The CaptchaBundle requires persistent per-user server storage to work properly. By default, it uses Symfony Session, which is convenient in most use cases.

If your environment requires a different approach to handle Session data, you can be easily looking for the documentation on symfony site. For example, in case, you want to store Sessions in the Database, then you can follow this cookbook entry to use PDOSessionHandler.

Note that a Session cleanup right after creating a Captcha class instance may cause an error since BotDetect will not find its Session data.

2. Display BotDetect CAPTCHA in Your Symfony Form

Captcha configuration options

<?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 CaptchaBundle, you must delare Captcha configuration in app/config/captcha.php file following the structure given above. The ExampleCaptcha is an example name and will be used as captcha field type, or to get a captcha object instance in some scenarios that you do not want to use captcha field type to display captcha in your form. You should pick a name that best matches your usage scenario like: LoginCaptcha, ContactCaptcha, etc. You can find a full list of available Captcha configuration options and related instructions at the Captcha configuration options page.

In case you need different Captcha for another form in your application, here is the example how to add additional captcha configuration for a login form:

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

// BotDetect PHP Captcha configuration options

return [
  // Captcha configuration for example page
  'ExampleCaptcha' => [
    'UserInputID' => 'captchaCode',
    'ImageWidth' => 250,
    'ImageHeight' => 50,

  // Captcha configuration for login page
  'LoginCaptcha' => [
    'UserInputID' => 'captchaCode',
    'CodeLength' => CaptchaRandomization::GetRandomCodeLength(4, 6),
    'ImageStyle' => [


Compose Your Symfony Form With BotDetect CAPTCHA Display

namespace AppBundle\Form\Type;

use Captcha\Bundle\CaptchaBundle\Form\Type\CaptchaType;

class ExampleType extends AbstractType
  public function buildForm(FormBuilderInterface $builder, array $options)
    $builder->add('captchaCode', CaptchaType::class, array(
      'captchaConfig' => 'ExampleCaptcha'

CaptchaBundle provides CaptchaType to add Captcha in your forms. It is required to declare captchaConfig option and assign it a captcha configuration key defined in app/config/captcha.php file. Notice, to denote the CaptchaType, we have to use the fully qualified class name - i.e. CaptchaType::class in PHP 5.5+ or Captcha\Bundle\CaptchaBundle\Form\Type\CaptchaType.

3. Validate CAPTCHA In Your Symfony Entity

Validate the Submitted CAPTCHA Code User Input

namespace AppBundle\Entity;

use Captcha\Bundle\CaptchaBundle\Validator\Constraints as CaptchaAssert;

class Example
   * @CaptchaAssert\ValidCaptcha(
   *      message = "CAPTCHA validation failed, try again."
   * )
  protected $captchaCode;

  public function getCaptchaCode()
    return $this->captchaCode;

  public function setCaptchaCode($captchaCode)
    $this->captchaCode = $captchaCode;

After Captcha is displayed in your form, you would want to validate the Captcha code user submitted. To do that, you should simply use the ValidCaptcha constraint in your entity that is available in the CaptchaBundle. You can also customize an error message by adding your custom error message to message option.

Handle CAPTCHA Validation Failure / Success

Symfony validation will abort further processing and display an error on failure, or proceed with a protected form action on success:

$form ->handleRequest($request);
if ($form->isValid()) {
  // TODO: Captcha validation passed:
  // continue with form processing, knowing the submission was made by a human

This ensures particular sensitive action to be executed only if a human filled the form.