README.md

GoogleReCaptchaBundle

ReCAPTCHA is a free CAPTCHA service that protects websites from spam and abuse. This bundle uses the GoogleReCaptcha library or validating a users "No CAPTCHA reCAPTCHA" response and provides a custom form type, a custom validation constraint as well as a validator to use with the Symfony Form Component.

Installation

The recommended way to install GoogleReCaptchaBundle is through Composer.

# Install Composer
curl -sS https://getcomposer.org/installer | php

Next, run the Composer command to install the latest stable version of GoogleReCaptcha:

composer require "nietonfir/google-recaptcha-bundle"

Or add GoogleReCaptchaBundle in your composer.json

"require": {
    "nietonfir/google-recaptcha-bundle": "v0.0.3"
}

and tell Composer to install the library:

composer update "nietonfir/google-recaptcha-bundle"

After installing, don't forget to enable the bundle:

<?php
// app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        // ...
        new Nietonfir\Google\ReCaptchaBundle\NietonfirGoogleReCaptchaBundle(),
    );
}

Configuration

Add the following simple configuration to your config.yml.

nietonfir_google_recaptcha:
    sitekey: <your_site_key_here>
    secret: <and_your_secret_here>
    validation: '<your_form_name>'

Multiple forms

ReCaptcha can also be added to different forms (while not on the same page!):

nietonfir_google_recaptcha:
    validation: [ '<your_form_name_A>', '<your_form_name_B>' ]

Custom form field name

The form field name containing the recaptcha response, which defaults to recaptcha, can be customized as well:

nietonfir_google_recaptcha:
    validation:
        forms:
            - {form_name: '<your_form_name_A>', field_name: 'recaptcha'}
            - {form_name: '<your_form_name_B>', field_name: 'recaptcha'}

Additionally you have to add the corresponding form field themes depending on your used templating engine in config.yml.

# Twig
twig:
    debug:            "%kernel.debug%"
    strict_variables: "%kernel.debug%"
    form_themes:
        - 'NietonfirGoogleReCaptchaBundle:Form:fields.html.twig'

# PHP
framework:
    templating:
        form:
            resources:
                - 'NietonfirGoogleReCaptchaBundle:Form'

Usage

Using the Bundle is dead simple:

1. Create your form type as usual

2. Add a field using the recaptcha field type

   use Nietonfir\Google\ReCaptchaBundle\Form\Type\ReCaptchaType;
   
   $builder->add('recaptcha', ReCaptchaType::class);

3. Add the necessary javascript library to your template

   <script src='https://www.google.com/recaptcha/api.js' async defer></script>

4. Make your controller implement ReCaptchaValidationInterface

   use Nietonfir\Google\ReCaptchaBundle\Controller\ReCaptchaValidationInterface;
   
   class DefaultController extends Controller implements ReCaptchaValidationInterface

Now when form->isValid() is called, the submitted reCAPTCHA response is validated against the Google API. Be advised that both the form and the field name used have to be set in config.yml.

TODOs

• Add some info() to the form & field name config values in Configuration.php
• Translate the error messages returned from the Google API to something more meaningful
• Update documentation
• Add some more examples
• Add missing unit tests