How to enable ReCaptcha v2 in Joomla 2.5

If you are running a Joomla 2.5 site you may have already encountered issues with your reCAPTCHA v1 keys, such as the warning message "V1 SHUTDOWN ON 2018-03-31". This happens because Joomla 2.5 supports only reCAPTCHA v1 API, while Google is shutting down v1 API in favor of v2 API.

After doing some research for one of our clients we could not find any working solution, so we decided to write our own patch for the existing Joomla 2.5 captcha/recaptcha plugin so it supports reCAPTCHA v2 API. We have also included instructions on how to call the new version of the plugin from a 3rd party component or other extension.

You can download the installation package file (for Joomla 2.5) by clicking on the link below:

Here is a screenshot of how it should look like:

If you have any questions feel free to contact us at

Please note that if you install the reCAPTCHA v2 upgrade not all existing extensions will magically be compatible with reCAPTCHA v2. More specifically:
  • An extension that is using the built-in reCAPTCHA plugin will continue to work with no extra effort.
  • An extension that is using a proprietary form of captcha (e.g. image based), will continue to use the same old form. No upgrade to reCAPTCHA can be done automatically.
  • An extension that is not using any form of captcha, will continue to be without a captcha protection. No insertion of the reCAPTCHA code can be done automatically.
For these reasons, if you want to enable the new reCAPTCHA on 3rd party extensions you will need to do some manual work. If you are not familiar with PHP programming, we can take care of them with a small fee. Contact us to request an offer.

Installation instructions

Step #1

Login in the backend of your Joomla 2.5 as admin and go to menu Extensions -> Extension Manager. Upload and Install the package file that you found in this distribution file.

Step #2

Visit the following URL to generate a V2 Google reCAPTCHA:

You need to sign in or sign up first, if you don't have a Google account :)

Fill out the form and click on the Register button:

For instance, for our site we have used the following settings:

Once you click on the Register button you will a success message, along with the Site Key and the Secret Key:

The Site Key should be assigned to the Public Key parameter of the Captcha - ReCaptcha plugin, while the Secret Key should be assigned to the Private Key parameter.

Step #3

This step is required only if you are using reCAPTCHA from a customized extension (components, plugin or module). Otherwise, you can skip this step.

If you are calling the captcha/reCaptcha plugin from your custom extension, or 3rd party extension, you may need to adjust the calling code.

More specifically, the new PHP code should look like this:

$dispatcher = JDispatcher::getInstance();

$reCaptchaName = 'plg_captcha_recaptcha';
$output = $dispatcher->trigger('onDisplay', array($reCaptchaName, 'dynamic_recaptcha_1', ''));
$recaptcha_div = $output[0];

Paste this snippet where you want the reCAPTCHA widget to appear:

<? echo $recaptcha_div; ?>

Old PHP code (must be replaced with the new code):

$dispatcher = JDispatcher::getInstance();

Paste this snippet where you want the reCAPTCHA widget to appear:

<div id="dynamic_recaptcha_1"></div>

That's it!


If you don't see the reCAPTCHA immediately you should examine the following two most common causes:

  • The reCAPTCHA public site key you received from Google is not valid. For that, download the test file from the URL and unzip it. Then, edit it and set the parameter RECAPTCHA_PUBLIC_KEY to the correct value. Finally, place the edited test-recaptcha.php anywhere on your site and visit it with a browser to see if the reCAPTCHA is visible. If not, you should re-generate the reCAPTCHA v2 keys.
  • You have not installed correctly the plugin. Make sure you follow the instructions properly.

If you are getting a fatal error or a blank page after installing the new version, you can revert to the older version. The original version is stored at {joomla root directory}/plugins/captcha/recaptcha/recaptcha.original.php. Rename it to recaptcha.php and you should be fine.