1# reCAPTCHA PHP client library
  2
  3[![Build Status](https://travis-ci.org/google/recaptcha.svg)](https://travis-ci.org/google/recaptcha)
  4[![Coverage Status](https://coveralls.io/repos/github/google/recaptcha/badge.svg)](https://coveralls.io/github/google/recaptcha)
  5[![Latest Stable Version](https://poser.pugx.org/google/recaptcha/v/stable.svg)](https://packagist.org/packages/google/recaptcha)
  6[![Total Downloads](https://poser.pugx.org/google/recaptcha/downloads.svg)](https://packagist.org/packages/google/recaptcha)
  7
  8reCAPTCHA is a free CAPTCHA service that protects websites from spam and abuse.
  9This is a PHP library that wraps up the server-side verification step required
 10to process responses from the reCAPTCHA service. This client supports both v2
 11and v3.
 12
 13- reCAPTCHA: https://www.google.com/recaptcha
 14- This repo: https://github.com/google/recaptcha
 15- Hosted demo: https://recaptcha-demo.appspot.com/
 16- Version: 1.2.4
 17- License: BSD, see [LICENSE](LICENSE)
 18
 19## Installation
 20
 21### Composer (recommended)
 22
 23Use [Composer](https://getcomposer.org) to install this library from Packagist:
 24[`google/recaptcha`](https://packagist.org/packages/google/recaptcha)
 25
 26Run the following command from your project directory to add the dependency:
 27
 28```sh
 29composer require google/recaptcha "^1.2"
 30```
 31
 32Alternatively, add the dependency directly to your `composer.json` file:
 33
 34```json
 35"require": {
 36    "google/recaptcha": "^1.2"
 37}
 38```
 39
 40### Direct download
 41
 42Download the [ZIP file](https://github.com/google/recaptcha/archive/master.zip)
 43and extract into your project. An autoloader script is provided in
 44`src/autoload.php` which you can require into your script. For example:
 45
 46```php
 47require_once '/path/to/recaptcha/src/autoload.php';
 48$recaptcha = new \ReCaptcha\ReCaptcha($secret);
 49```
 50
 51The classes in the project are structured according to the
 52[PSR-4](http://www.php-fig.org/psr/psr-4/) standard, so you can also use your
 53own autoloader or require the needed files directly in your code.
 54
 55## Usage
 56
 57First obtain the appropriate keys for the type of reCAPTCHA you wish to
 58integrate for v2 at https://www.google.com/recaptcha/admin or v3 at
 59https://g.co/recaptcha/v3.
 60
 61Then follow the [integration guide on the developer
 62site](https://developers.google.com/recaptcha/intro) to add the reCAPTCHA
 63functionality into your frontend.
 64
 65This library comes in when you need to verify the user's response. On the PHP
 66side you need the response from the reCAPTCHA service and secret key from your
 67credentials. Instantiate the `ReCaptcha` class with your secret key, specify any
 68additional validation rules, and then call `verify()` with the reCAPTCHA
 69response and user's IP address. For example:
 70
 71```php
 72<?php
 73$recaptcha = new \ReCaptcha\ReCaptcha($secret);
 74$resp = $recaptcha->setExpectedHostname('recaptcha-demo.appspot.com')
 75                  ->verify($gRecaptchaResponse, $remoteIp);
 76if ($resp->isSuccess()) {
 77    // Verified!
 78} else {
 79    $errors = $resp->getErrorCodes();
 80}
 81```
 82
 83The following methods are available:
 84
 85- `setExpectedHostname($hostname)`: ensures the hostname matches. You must do
 86  this if you have disabled "Domain/Package Name Validation" for your
 87  credentials.
 88- `setExpectedApkPackageName($apkPackageName)`: if you're verifying a response
 89  from an Android app. Again, you must do this if you have disabled
 90  "Domain/Package Name Validation" for your credentials.
 91- `setExpectedAction($action)`: ensures the action matches for the v3 API.
 92- `setScoreThreshold($threshold)`: set a score threshold for responses from the
 93  v3 API
 94- `setChallengeTimeout($timeoutSeconds)`: set a timeout between the user passing
 95  the reCAPTCHA and your server processing it.
 96
 97Each of the `set`\*`()` methods return the `ReCaptcha` instance so you can chain
 98them together. For example:
 99
100```php
101<?php
102$recaptcha = new \ReCaptcha\ReCaptcha($secret);
103$resp = $recaptcha->setExpectedHostname('recaptcha-demo.appspot.com')
104                  ->setExpectedAction('homepage')
105                  ->setScoreThreshold(0.5)
106                  ->verify($gRecaptchaResponse, $remoteIp);
107
108if ($resp->isSuccess()) {
109    // Verified!
110} else {
111    $errors = $resp->getErrorCodes();
112}
113```
114
115You can find the constants for the libraries error codes in the `ReCaptcha`
116class constants, e.g. `ReCaptcha::E_HOSTNAME_MISMATCH`
117
118For more details on usage and structure, see [ARCHITECTURE](ARCHITECTURE.md).
119
120### Examples
121
122You can see examples of each reCAPTCHA type in [examples/](examples/). You can
123run the examples locally by using the Composer script:
124
125```sh
126composer run-script serve-examples
127```
128
129This makes use of the in-built PHP dev server to host the examples at
130http://localhost:8080/
131
132These are also hosted on Google AppEngine Flexible environment at
133https://recaptcha-demo.appspot.com/. This is configured by
134[`app.yaml`](./app.yaml) which you can also use to [deploy to your own AppEngine
135project](https://cloud.google.com/appengine/docs/flexible/php/download).
136
137## Contributing
138
139No one ever has enough engineers, so we're very happy to accept contributions
140via Pull Requests. For details, see [CONTRIBUTING](CONTRIBUTING.md)
141