Using Yireo reCAPTCHA for Magento

The Yireo reCAPTCHA module allows you to easily implement reCAPTCHA into Magento, without coding and without core-hacks. This tutorial shows you what you should do to implement reCAPTCHA into your site.

Sign up for reCAPTCHA

recaptcha-examplereCAPTCHA is software of Google, and to use reCAPTCHA on your site, you will need to register yourself on the Google site. Within your account settings, Google will generate a public key and private key. Note that a key-pair is generated for every domain. If you want to use this Magento extension on multiple domain names, you will need to generate multiple key-pairs. The Yireo reCAPTCHA can be used without limits on any domain you want.

Get the Yireo reCAPTCHA module

The Yireo reCAPTCHA module is for sale on our site. Once purchased, you can download the latest version of this extension at any time by navigating to your Yireo Account. The extension is only available in the form of a ZIP file, and is not available through MagentoConnect.

Installing the Yireo reCAPTCHA module

Download the ZIP file to your computer, extract all files and upload those files to the Magento root folder using FTP or SSH. The ZIP file contains the following folders which correspond with existing folders in Magento:

  • app/etc/modules
  • app/code/community
  • app/design/frontend/base/default/layout
  • app/design/frontend/base/default/templates

Refresh Magento caching

After uploading these files and folders to Magento, refresh the Magento cache. You can either do this from the Magento backend (System > Cache Management). Or you could also remove the entire var/cache folder through FTP or SSH to remove the cache manually.

Configuring the reCAPTCHA settings

Next, login to the Magento Admin Panel and browse to System > Configuration. Select the right scope (Store or Store View) to configure. Then navigate to Yireo > Recaptcha. This should display a panel like below. If this panel does not appear, logout from the Magento Admin Panel and log back in again.


Within this panel, you will need to configure the Secret Key and the Site Key as generated on the official reCAPTCHA website. You can also configure the theme to be used. The best theme is probably clean, but you can also choose red, white or blackglass. The theme custom is for experts only.

You can also simply choose for which pages to enable reCAPTCHA:

  • Customer registration page
  • Customer login page
  • Customer forgotpassword page
  • Contact form
  • Send-to-a-friend form
  • Product review form
  • OnePageCheckout login
  • OnePageCheckout billing

Modifying PHTML-templates

You can also modify PHTML templates yourself. Any PHTML template can be easily configured with Yireo reCAPTCHA by adding the following code to it:

<?php echo $this->getBlockHtml('recaptcha')?>

The line of code will automatically initiate reCAPTCHA for that Magento block, while the internal workings of the Yireo extension will make sure that the POST feedback is checked correctly. Only make sure that the PHP line is outputting HTML within a <form> element, otherwise it will not be sent with the POST reply:

<?php echo $this->getBlockHtml('recaptcha')?>

If you want to modify the original Magento PHTML templates - for instance: the product review page - you have 2 options: You can either modify the original Magento template review/form.phtml and add the PHP line yourself, or you can modify the reCAPTCHA copy of this form through recaptcha/review/form.phtml.

The following PHTML templates are included in the reCAPTCHA template folder:

  • recaptcha/contacts/form.phtml = Copy of contacts form
  • recaptcha/sendfriend/send.phtml = Copy of send-a-friend form
  • customer/form/register.phtml = Copy of customer registration form
  • customer/form/login.phtml = Copy of customer login form
  • customer/form/forgotpassword.phtml = Copy of customer forgotpassword form
  • review/form.phtml = Copy of product review

Configuring custom URLs

When using new Magento blocks for usage with reCAPTCHA, also make sure to configure the option Custom URLs. This option makes sure that the reCAPTCHA code is still being checked, if the POST data does not contain reCAPTCHA fields: Robot scripts would apply this track.

The Custom URLs option is a newline separated list of URLs to which POST data are sent. Note that this URL is not the same as the URL which displays the form. For instance, the URL customer/account/login displays the login-form. But the URL customer/account/loginPost handles the actual POST-data - so this second URL should be used in the option Custom URLs.

How the Yireo reCAPTCHA module works

The Yireo reCAPTCHA module works completely transparent. The only thing you need to do is add the block-call $this->getBlockHtml('recaptcha') to another PHTML template, and that's it. The extension will capture any POST request being received by Magento, and will check whether that POST request should be checked using CAPTCHA. If so, it does so.

Using the "custom" theme

When you choose as theme custom, you can fully style how reCAPTCHA appears on your site. Modifiying also becomes more complex. To modify the HTML output, the PHTML template recaptcha/custom.phtml can be overridden by your own Magento theme. The custom theme does not come with any CSS code so you need to write that yourself.

Regarding the legacy mode

Recaptcha has various modes: The current mode is to display a simple I Am Human check. The previous mode showed a puzzle of distorted letters. The previous mode is still present under the current extension, dubbed as Legacy. The Legacy settings can be found under General > Web > Recaptcha. If you want to use the legacy mode, you can still configure the settings there. If you only want to use the new mode, ignore the legacy settings.

Adding the block in CMS content

Within Magento 1.9, security measures were introduced which prevents the insertion of blocks in CMS content (like widgets, CMS pages and Static Blocks). To bypass this, the type of the block needs to be inserted in the page backend System > Permisssions > Blocks. For the Recaptcha plugin this type is recaptcha/default.

Error: Could not open socket

When this error occurs, your webserver is not able to make outgoing calls to the Google API. Check with your hosting provider that there's no internal firewall blocking this, or restart the webserver to try again.

Troubleshooting CSS-code

Sometimes the Recaptcha box might be misaligned with other HTML elements, something that needs to be solved with CSS. Our extension adds the Recaptcha field to various page elements, but wraps it within a div with ID recaptcha-outer-box. Because the Recaptcha scripts set the various child elements using absolute positioning, it is wise to define the outerbox as relative.

div#recaptcha-outer-box { position: relative; }

You might also need to define the height of this box:

div#recaptcha-outer-box { position: relative; height: 120px; }

If you use this Recaptcha for Magento extension within Joomla! (using MageBridge), beware that Joomla! contains some default CSS that styles the various Recaptcha elements. For instance, the recaptcha_widget_div has a top of -140px, which makes things look weird. This could be reset using something like this:

div#recaptcha_widget_div { top: 0 !important; }

Inspecting the applied CSS code using Firebug or other development tools, might reveil further styling.


The reCAPTCHA widget can only be added to a page once. The second widget you will add to the same page will not work. This is a current limitation of the Google reCAPTCHA scripts.