Developers

Extend any custom form or add support for existing Magento forms.

📘

Tutorial Extension Available

We have a GitHub repository with examples of how to use the following information in a Magento extension available on GitHub

How it works

The extension utilizes the Magento observer controller_action_predispatch which runs before the forms are processed by Magento. The observer sends the response from the client-side reCAPTCHA check to Google for server-side verification and if successful, the form processes as normal. If the verification fails, we redirect back to the form page and notify your customer that they failed the reCAPTCHA test.

Extension Points

On top of what Magento already offers, we've created two more developer-friendly observers:

1. studioforty9_recaptcha_routes
2. studioforty9_recaptcha_failed

studioforty9_recaptcha_routes

In the configuration section for the extension, we allow admins to configure the routes on which reCAPTCHA should run but as a developer you can add your own routes too.

config.xml

<!-- File: app/code/local/Namespace/YourModule/etc/config.xml -->
<config>
  <modules>
    <Namespace_YourModule>
      <version>1.0.0</version>
    </Namespace_YourModule>
  </modules>
  <global>
    <models>
      <namespace_yourmodule>
        <class>Namespace_YourModule_Model</class>
      </namespace_yourmodule>
    </models>
    <events>
      <studioforty9_recaptcha_routes>
        <observers>
          <add_recaptcha_route>
            <class>namespace_yourmodule/observer</class>
            <method>addRecaptchaRouteToConfiguration</method>
          </add_recaptcha_route>
        </observers>
      </studioforty9_recaptcha_routes>
    </events>
  </global>
</config>

The observer holds an instance of the Studioforty9_Recaptcha_Model_Routes class, which you can use to adapt the list to your needs.

PHP

<?php

// File: app/code/local/Namespace/YourModule/Model/Observer.php

class Namespace_YourModule_Model_Observer
{
   /**
   * Add the route for the form to the available selections in configuration.
   *
   * @param Varien_Event_Observer $observer The dispatched observer
   */
  public function addRecaptchaRouteToConfiguration(Varien_Event_Observer $observer)
  {
    $observer->getRoutes()->add('route_controller_action', 'Sample Form');
  }
}

❗️

Enable your form via Configuration

Don't forget to enable your form by selecting it under System-> Configuration -> Sales -> Google API -> Google reCAPTCHA -> Enabled Routes.

studioforty9_recaptcha_failed

When the reCAPTCHA verification fails, it can be useful to run additional code, for example to re-populate a form with the request's POST data etc.

We also provide an observer with the exact route name of the form being processed. For example, the product review form has a route of review_product_post and we make the following observer available for that form: studioforty9_recaptcha_failed_review_product_post.

config.xml

<!-- File: app/code/local/Namespace/YourModule/etc/config.xml -->
<config>
  <modules>
    <Namespace_YourModule>
      <version>1.0.0</version>
    </Namespace_YourModule>
  </modules>
  <global>
    <models>
      <namespace_yourmodule>
        <class>Namespace_YourModule_Model</class>
      </namespace_yourmodule>
    </models>
  </global>
  <frontend>
    <events>
      <studioforty9_recaptcha_failed>
        <observers>
          <namespace_yourmodule>
            <class>namespace_yourmodule/observer</class>
            <method>onFailedRecaptcha</method>
          </namespace_yourmodule>
        </observers>
      </studioforty9_recaptcha_failed>
      <studioforty9_recaptcha_failed_route_controller_action>
        <observers>
          <namespace_yourmodule>
            <class>namespace_yourmodule/observer</class>
            <method>onFailedRecaptchaRouteControllerAction</method>
          </namespace_yourmodule>
        </observers>
      </studioforty9_recaptcha_failed_route_controller_action>
    </events>
  </frontend>
</config>

Observer Code

You have access to 2 objects in the observer:

1. The current controller action, usually extends from Mage_Core_Controller_Front_Action. For example, if you are running your observer on the contacts form, your controller class would be Mage_Contacts_IndexController. You have access to the request object via $observer->getEvent()->getControllerAction()->getRequest()

2. The response object with the type of error sent back from Google Studioforty9_Recaptcha_Helper_Response. You can retrieve the response errors via $observer->getEvent()->getRecaptchaResponse()->getErrors()

PHP

<?php

// File: app/code/local/Namespace/YourModule/Model/Observer.php

class Namespace_YourModule_Model_Observer
{
  public function onFailedRecaptcha(Varien_Event_Observer $observer)
  {
    /** @var Mage_Core_Controller_Front_Action $controller */
    $controller = $observer->getEvent()->getControllerAction();
    /** @var Studioforty9_Recaptcha_Helper_Response $response */
    $response = $observer->getEvent()->getRecaptchaResponse();
  }
  
  public function onFailedRecaptchaRouteControllerAction(Varien_Event_Observer $observer)
  {
    $data = $observer->getEvent()->getControllerAction()->getRequest()->getPost();
    Mage::getSingleton('core/session')->setFormData($data);
  }
}