README

A wrapper class for ReCaptcha to make integrating into your site dead simple.

Created with love by HTMLGuy, LLC

Important Notes:

Will use Guzzle by default, if available...otherwise fallsback to CURL with non-ideal settings (SSL_VERIFY_PEER/SSL_VERIFY_HOST = false) - I recommend you add a cacert and pass "true, true" to the verify method (see definition for details)
If ANYTHING fails (with the exception of a missing IP address), it will default to allowing the request. This way you don't miss out if recaptcha is down or something.

To use:

Create an account on Google and navigate to their ReCaptcha service here:

https://www.google.com/recaptcha/admin

Include PHPRecaptcha in your site with composer:

composer require htmlguyllc/phprecaptcha

Either Copy the google_credentials.example.ini and create a file named google_credentials.ini in the same folder:

Swap out {{YOUR_SECRET}} for the Secret key on Google.
Swap out {{YOUR_SITE_KEY}} for the Site Key on google.

OR set your credentials in environment variables with the following keys:

RECAPTCHA_SECRET
RECAPTCHA_SITE_KEY

OR store your credentials however you want, and pass them during instantiation:

$captcha = new \HTMLGuyLLC\ReCaptcha($secret, $site_key);

Include the following in your HTML:

<script src='https://www.google.com/recaptcha/api.js'></script>

Use the following where you want to display the captcha (presumably in a form):

$captcha = new \HTMLGuyLLC\ReCaptcha();
echo $captcha->display();

To validate a captcha after it's been completed and the form has been posted, run the verify() method.

try
{
    $captcha = new \HTMLGuyLLC\ReCaptcha();
    if( !$captcha->verify() )
    {
        //user failed to complete the captcha correctly
    }
}
catch(\HTMLGuyLLC\ReCaptchaExeption $e)
{
    //do something specific for errors with recaptcha or this class
}
catch(\Exception $e)
{
    //catch any unexpected exceptions
}

In Javascript, if you use AJAX to submit the form, you'll want to regenerate the captcha. Use the following in your AJAX complete callback:

grecaptcha.reset();

Implementation idea:

You can add a global AJAX "complete" callback which updates any captcha on the page by default by using the following:

$(document).ajaxComplete(function(event,request,settings){
  if( typeof grecaptcha !== 'undefined' )
  {
   grecaptcha.reset()
  }
});

Dependencies

PHP, CURL, ReCaptcha, Guzzle (optional)

Changelog

1.0

Initial

1.1

Include support for environment variables

1.2

Allow override of curl verify host/peer options in verify() method

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

htmlguyllc / phprecaptcha

Maintainers

Details