README

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:

Create your form type as usual

Add a field using the recaptcha field type

use Nietonfir\Google\ReCaptchaBundle\Form\Type\ReCaptchaType;

$builder->add('recaptcha', ReCaptchaType::class);

Add the necessary javascript library to your template

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

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

nietonfir / google-recaptcha-bundle

Maintainers

Details