reCAPTCHA

This module makes it easy to make use of Google's v2 Invisible reCAPTCHA to protect your Magento 1.x store's forms against spam and other types of automated abuse. It was created in order to protect some of our forms on parkandfinch.com, which, at the time this was created, was running Magento CE 1.9.3.10.

Features

• Easy integration. Simply add a div to your form after setting up the module!
• Support for non-Magento-native forms out of the box. A lot of existing modules seem to focus mainly on protecting forms generated by Magento
• Add reCAPTCHAs to as many forms as you want on a page in the same manner
• Option to easily hide the badge that hovers on the user's screen by default

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes in preparation for deployment.

Prerequisites

• You'll need a reCAPTCHA API key pair for your sites. If you haven't already done so, you'll need to start by signing up with Google to get it. To do this:
  1. Head to Google's reCAPTCHA Registration Page and sign in to a Google account you want to use to manage your store's reCAPTCHA settings
  2. For the type, make sure to select reCAPTCHA v2 with the invisible reCAPTCHA badge
  3. In the Domains section, make sure to add all the relevant domains you use for your store. For example, if you have separate domains for different countries, e.g. parkandfinch.com and parkandfinch.ca, you'll have to enter all the variants here, as the reCAPTCHA will only work when loaded from these configured domains by default
  4. Upon successful form submission, you'll be presented with the key pair you'll need to configure this module

Installation

Option 1: Modman

• Install modman
• Run this command from your Magento installation folder:

modman clone [https://github.com/nleduc/reCAPTCHA](https://github.com/nleduc/reCAPTCHA)

Option 2: Composer

• Install composer
• Install Magento Composer
• Create a composer.json in your project, if you don't already have one, that contains the following:

{
    "require": {
        "parkandfinch/recaptcha":"*"
    },
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/nleduc/reCAPTCHA"
        }
    ],
    "extra":{
        "magento-root-dir": "./"
    }
}

The magento-root-dir value of "./" assumes your magento files are installed in your project root directory, if they are not, adjust the value accordingly.

• Run a composer update

Option 3: Manual

• You can simply copy the files from the folders of this repository to the same folders of your Magento installation, which is often what the above methods end up doing ultimately

Post-installation steps

• Log into your store's admin section
• Flush your cache.
  • E.g. System > Cache Management > Flush Magento Cache
• Log out and then log back in

Configuration

Once installed, all the configuration options will appear under a new tab called PARKANDFINCH MODULES in the admin:

Select "reCAPTCHA Configuration" to configure the module.

You'll be presented with this form:

This is where you'll have to enter the reCAPTCHA key pair you obtained from Google. If you're testing in a development environment, check out the Google reCAPTCHA Code Lab which explains how you can use a key pair specific to your local environment.

The last option allows you to hide the little reCAPTCHA badge that will hover within the user's window. Google does allow you to remove it, but they do ask that you add some branding, which I've included as an optional template in this module. Below is a screencap of the badge in question:

Below is an example of the optional template you can choose to show when hiding the badge. It contains the HTML snippet recommended by Google:

Usage

Once the module is configured, integration can be as easy as adding this empty div within any form you want to protect:

    <div class='g-recaptcha'></div>

and then adding a check in the scripts that handle the requests generated by those forms to see if the reCAPTCHA reported a success or failure:

if (!Mage::helper('recaptcha')->isReCaptchaSuccessful()) {
    // block the action
} else {
    // proceed with the action
}

Example

In our case we had a newsletter sign-up form in the footer we wanted to protect, so I did the following:

Include the recaptcha block and the optional branding block in the block that will contain them

While you can simply add an empty div with a 'g-recaptcha' class within whatever form you want to protect, the best practice is to include the recaptcha block in your layout and then output the recaptcha container using:

<?php echo $this->getChildHtml('parkandfinch.recaptcha'); ?>

In my case it was the footer, and I wanted to show the Google branding to warn my users that the form is reCAPTCHA-protected, so I set up the following in my layout/local.xml file:

<?xml version="1.0"?>  
<layout>  
...
    <default>
        <reference name="footer">  
            <block type="parkandfinch_recaptcha/recaptcha" name="recaptcha.branding" template="parkandfinch/recaptcha/branding.phtml" />  
            <block type="parkandfinch_recaptcha/recaptcha" name="parkandfinch.recaptcha" template="parkandfinch/recaptcha/recaptcha.phtml" />  
        </reference>
    </default>
...
</layout>

Output the reCAPTCHA div and branding in the form

Because my form is in my footer, I edited my extended template/page/html/footer.phtml file to echo the two values for my form:

    ...
    <form action="/newsletter/subscriber/new/" method="post" id="newsletter-validate-detail">
        <?php echo $this->getChildHtml('parkandfinch.recaptcha'); ?>
        <label for="newsletter">Sign Up for Our Newsletter:</label>
        <input type="email" name="email">
        <button type="submit">Go</button>
    </form>
    <?php echo $this->getChildHtml('recaptcha.branding'); ?>
    ...

Only two lines were added, the recaptcha div itself, which is simply an empty div with class 'g-recaptcha':

<?php echo $this->getChildHtml('parkandfinch.recaptcha'); ?>

and the optional one for the branding snippet:

<?php echo $this->getChildHtml('recaptcha.branding'); ?>

Process the reCAPTCHA response

Now we simply need to check the value of

Mage::helper('recaptcha')->isReCaptchaSuccessful()

and choose to allow the subscription to go through or not. In this case, there are two options, we can either extend/update the code that processes the POST from the form to check for this condition, or, because Magento dispatches an event when a user attempts to subscribe to a newsletter, we can add an Observer for that event and add our check there without touching the existing code. I chose to do the latter.

While I created an Observer, the logic is the same for processing the reCAPTCHA response, so I'll share the code snippet I wrote:

class ParkAndFinch_AjaxNewsletterSignup_Model_Observer
{
   /**
    * Used to intercept the newsletter signup request and validate the reCAPTCHA if it's enabled
    * 
    * While it throws an exception with a message, it causes a more general exception to be thrown, so the message is
    * lost and it'll just show the user an error that there was a problem with the subscription
    * 
    * @param Varien_Event_Observer $observer
    * @throws Mage_Core_Exception
    */
    public function interceptNewsletterSignup(Varien_Event_Observer $observer)
    {
        if (!Mage::helper('core')->isModuleEnabled('ParkAndFinch_ReCaptcha')) {
           return;
        }

        /**
         * @var $reCaptchaHelper ParkAndFinch_Recaptcha_Helper_Data
         */
        $reCaptchaHelper = Mage::helper('recaptcha');

        if ($reCaptchaHelper->isReCaptchaEnabled() && !$reCaptchaHelper->isReCaptchaSuccessful()) {
            Mage::throwException($reCaptchaHelper->__('Blocked by Google reCAPTCHA.'));
        }
    }
}

Authors

Nicholas Leduc - Owner of Park and Finch Eyewear