PHP Library to support Google captcha.

v0.3.0 2014-12-16 09:49 UTC

This package is not auto-updated.

Last update: 2020-09-18 19:23:28 UTC


ReCaptcha is a free CAPTCHA service that protect websites from spam and abuse. This provides plugins for third-party integration with ReCAPTCHA.

This supports the latest Google ReCaptcha with the "I'm not a robot" tickbox.


Composer is used for installation.

curl -s | php
php composer.phar install

Your composer.json file should look like this:

  require: {
    "phpninjas/recaptcha": "~0.3"


To load the ReCaptcha on your page.

    <div class="g-recaptcha" data-sitekey="your_site_key"></div>
    <script src="" async defer></script>

To verify the captcha at server side.

require_once "vendor/autoload.php";

use Google\ReCaptcha;

$recaptcha = new ReCaptcha($secret);
$resp = $recaptcha->validate($_POST['g-recaptcha-response']);


Stubbing for tests

As most people want to be able to stub out the behaviour of a valid/invalid recaptcha it makes sense to be able to do this. Simply replace the http adapter with a mocked/stubbed one and you can validate the functionality of the the recaptcha library in the context of your code.


require_once "vendor/autoload.php"

class MyTest extends \PHPUnit_Framework_TestCase {

    public function testValidRecaptcha(){

        $goodResponse = [
          "success" => true

        $mockAdapter = $this->getMock('Google\HttpClientGetAdapter');

        $recaptcha = new ReCaptcha("secret", $mockAdapter);
        $this->assertThat($recaptcha->validate("my token thing"), $this->equalTo(new ReCaptchaResponse(true)));

    public function testInvalidRecaptcha(){
        $badResponse = [
          "success" => false,
          "error-codes" => ["error1"]

        $mockAdapter = $this->getMock('Google\HttpClientGetAdapter');

        $recaptcha = new ReCaptcha("secret", $mockAdapter);
        $this->assertThat($recaptcha->validate("my token thing"), $this->equalTo(new ReCaptchaResponse(false, ["error1"])));

Rest Handlers

By default this library ships with a very skinny http client. This client CAN throws warnings due to network errors. If you want to use something more professional I would recommend looking at Guzzle or another HTTP Client that provides better request/response handling. Until that time the default adapter should suffice.

If you want to provide a separate http adapter then simply implement the HttpClientGetAdapter interface and the only required method.

class MyHttpClient implements Google\HttpClientGetAdapter {
    public function get($uri){
        // do http magics here
        // fsockopen?
        // guzzle->get()
        // curl_exec()
        return $body

$recaptcha = new ReCaptcha("secret", new MyHttpClient());
$recaptcha->validate("response token");

Exception Handling

By default the ReCaptcha library handles any exceptions thrown by the http client that it utilises. These get wrapped into ReCaptchaException objects (which contain the inner exception). Thereby you only need to handle 1 exception when utilising the recaptcha.

try {
    $recaptcha = new ReCaptcha("secret", new Guzzle());
    $recaptcha->validate("response token");
} catch(ReCaptchaException $e){
    // peek at the inner exception