Merge pull request google#242 from google/v1.2

Version 1.2

Author: rowan-m

.gitignore

@@ -1,3 +1,6 @@
+/.php_cs.cache
+/build
 /composer.lock
+/examples/config.php
 /nbproject/private/
 /vendor/

.travis.yml

@@ -9,15 +9,19 @@ php:
   - '5.6'
   - '7.0'
   - '7.1'
-  - nightly
 
 before_script:
   - composer install
   - phpenv version-name | grep ^5.[34] && echo "extension=apc.so" >> ~/.phpenv/versions/$(phpenv version-name)/etc/php.ini ; true
   - phpenv version-name | grep ^5.[34] && echo "apc.enable_cli=1" >> ~/.phpenv/versions/$(phpenv version-name)/etc/php.ini ; true
 
 script:
-  - vendor/bin/phpunit
+  - mkdir -p build/logs
+  - composer run-script lint
+  - composer run-script test
+
+after_success:
+  - travis_retry php vendor/bin/php-coveralls
 
 cache:
   directories:

ARCHITECTURE.md

@@ -0,0 +1,56 @@
+# Architecture
+
+The general pattern of usage is to instantiate the `ReCaptcha` class with your
+secret key, specify any additional validation rules, and then call `verify()`
+with the reCAPTCHA response and user's IP address. For example:
+
+```php
+<?php
+$recaptcha = new \ReCaptcha\ReCaptcha($secret);
+$resp = $recaptcha->setExpectedHostname('recaptcha-demo.appspot.com')
+                  ->verify($gRecaptchaResponse, $remoteIp);
+if ($resp->isSuccess()) {
+    // Verified!
+} else {
+    $errors = $resp->getErrorCodes();
+}
+```
+
+By default, this will use the
+[`stream_context_create()`](https://secure.php.net/stream_context_create) and
+[`file_get_contents()`](https://secure.php.net/file_get_contents) to make a POST
+request to the reCAPTCHA service. This is handled by the
+[`RequestMethod\Post`](./src/ReCaptcha/RequestMethod/Post.php) class.
+
+## Alternate request methods
+
+You may need to use other methods for making requests in your environment. The
+[`ReCaptcha`](./src/ReCaptcha/ReCaptcha.php) class allows an optional
+[`RequestMethod`](./src/ReCaptcha/RequestMethod.php) instance to configure this.
+For example, if you want to use [cURL](https://secure.php.net/curl) instead you
+can do this:
+
+```php
+<?php
+$recaptcha = new \ReCaptcha\ReCaptcha($secret, new \ReCaptcha\RequestMethod\CurlPost());
+```
+
+Alternatively, you can also use a [socket](https://secure.php.net/fsockopen):
+
+```php
+<?php
+$recaptcha = new \ReCaptcha\ReCaptcha($secret, new \ReCaptcha\RequestMethod\SocketPost());
+```
+
+## Adding new request methods
+
+Create a class that implements the
+[`RequestMethod`](./src/ReCaptcha/RequestMethod.php) interface. The convention
+is to name this class `RequestMethod\`_MethodType_`Post` and create a separate
+`RequestMethod\`_MethodType_ class that wraps just the calls to the network
+calls themselves. This means that the `RequestMethod\`_MethodType_`Post` can be
+unit tested by passing in a mock. Take a look at
+[`RequestMethod\CurlPost`](./src/ReCaptcha/RequestMethod/CurlPost.php) and
+[`RequestMethod\Curl`](./src/ReCaptcha/RequestMethod/Curl.php) with the matching
+[`RequestMethod/CurlPostTest`](./tests/ReCaptcha/RequestMethod/CurlPostTest.php)
+to see this pattern in action.

CONTRIBUTING.md

@@ -1,24 +1,49 @@
-Want to contribute? Great! First, read this page (including the small print at the end).
+# Contributing
 
-### Before you contribute
-Before we can use your code, you must sign the
-[Google Individual Contributor License Agreement](https://developers.google.com/open-source/cla/individual?csw=1)
+Want to contribute? Great! First, read this page (including the small print at
+the end).
+
+## Contributor License Agreement
+
+Before we can use your code, you must sign the [Google Individual Contributor
+License
+Agreement](https://developers.google.com/open-source/cla/individual?csw=1)
 (CLA), which you can do online. The CLA is necessary mainly because you own the
 copyright to your changes, even after your contribution becomes part of our
 codebase, so we need your permission to use and distribute your code. We also
 need to be sure of various other things—for instance that you'll tell us if you
 know that your code infringes on other people's patents. You don't have to sign
-the CLA until after you've submitted your code for review and a member has
-approved it, but you must do it before we can put your code into our codebase.
-Before you start working on a larger contribution, you should get in touch with
-us first through the issue tracker with your idea so that we can help out and
-possibly guide you. Coordinating up front makes it much easier to avoid
-frustration later on.
+the CLA until after you've submitted your code for review (a link will be
+automatically added to your Pull Request) and a member has approved it, but you
+must do it before we can put your code into our codebase. Before you start
+working on a larger contribution, you should get in touch with us first through
+the issue tracker with your idea so that we can help out and possibly guide you.
+Coordinating up front makes it much easier to avoid frustration later on.
+
+## Linting and testing
+
+We use PHP Coding Standards Fixer to maintain coding standards and PHPUnit to
+run our tests. For convenience, there are Composer scripts to run each of these:
 
-### Code reviews
-All submissions, including submissions by project members, require review. We
-use GitHub pull requests for this purpose.
+```sh
+composer run-script lint
+composer run-script test
+```
+
+These are run automatically by [Travis
+CI](https://travis-ci.org/google/recaptcha) against your Pull Request, but it's
+a good idea to run them locally before submission to avoid getting things
+bounced back. That said, tests can be a little daunting so feel free to submit
+your PR and ask for help.
+
+## Code reviews
+
+All submissions, including submissions by project members, require review.
+Reviews are conducted on the Pull Requests. The reviews are there to ensure and
+improve code quality, so treat them like a discussion and opportunity to learn.
+Don't get disheartened if your Pull Request isn't just automatically approved.
 
 ### The small print
-Contributions made by corporations are covered by a different agreement than
-the one above, the Software Grant and Corporate Contributor License Agreement.
+
+Contributions made by corporations are covered by a different agreement than the
+one above, the Software Grant and Corporate Contributor License Agreement.

README.md

@@ -1,115 +1,139 @@
 # reCAPTCHA PHP client library
 
 [![Build Status](https://travis-ci.org/google/recaptcha.svg)](https://travis-ci.org/google/recaptcha)
+[![Coverage Status](https://coveralls.io/repos/github/google/recaptcha/badge.svg)](https://coveralls.io/github/google/recaptcha)
 [![Latest Stable Version](https://poser.pugx.org/google/recaptcha/v/stable.svg)](https://packagist.org/packages/google/recaptcha)
 [![Total Downloads](https://poser.pugx.org/google/recaptcha/downloads.svg)](https://packagist.org/packages/google/recaptcha)
 
-* Project page: http://www.google.com/recaptcha/
-* Repository: https://github.com/google/recaptcha
-* Version: 1.1.3
-* License: BSD, see [LICENSE](LICENSE)
-
-## Description
-
 reCAPTCHA is a free CAPTCHA service that protect websites from spam and abuse.
-This is Google authored code that provides plugins for third-party integration
-with reCAPTCHA.
+This is a PHP library that wraps up the server-side verification step required
+to process responses from the reCAPTCHA service. This client supports both v2
+and v3.
+
+- reCAPTCHA: https://www.google.com/recaptcha
+- This repo: https://github.com/google/recaptcha
+- Version: 1.2
+- License: BSD, see [LICENSE](LICENSE)
 
 ## Installation
 
-### Composer (Recommended)
+### Composer (recommended)
 
-[Composer](https://getcomposer.org/) is a widely used dependency manager for PHP
-packages. This reCAPTCHA client is available on Packagist as
-[`google/recaptcha`](https://packagist.org/packages/google/recaptcha) and can be
-installed either by running the `composer require` command or adding the library
-to your `composer.json`. To enable Composer for you project, refer to the
-project's [Getting Started](https://getcomposer.org/doc/00-intro.md)
-documentation.
+Use [Composer](https://getcomposer.org) to install this library from Packagist:
+[`google/recaptcha`](https://packagist.org/packages/google/recaptcha)
 
-To add this dependency using the command, run the following from within your
-project directory:
-```
-composer require google/recaptcha "~1.1"
+Run the following command from your project directory to add the dependency:
+
+```sh
+composer require google/recaptcha "^1.2"
 ```
 
 Alternatively, add the dependency directly to your `composer.json` file:
+
 ```json
 "require": {
-    "google/recaptcha": "~1.1"
+    "google/recaptcha": "^1.2"
 }
 ```
 
-### Direct download (no Composer)
+### Direct download
 
-If you wish to install the library manually (i.e. without Composer), then you
-can use the links on the main project page to either clone the repo or download
-the [ZIP file](https://github.com/google/recaptcha/archive/master.zip). For
-convenience, an autoloader script is provided in `src/autoload.php` which you
-can require into your script instead of Composer's `vendor/autoload.php`. For
-example:
+Download the [ZIP file](https://github.com/google/recaptcha/archive/master.zip)
+and extract into your project. An autoloader script is provided in
+`src/autoload.php` which you can require into your script. For example:
 
 ```php
-require('/path/to/recaptcha/src/autoload.php');
+require_once '/path/to/recaptcha/src/autoload.php';
 $recaptcha = new \ReCaptcha\ReCaptcha($secret);
 ```
 
 The classes in the project are structured according to the
-[PSR-4](http://www.php-fig.org/psr/psr-4/) standard, so you may of course also
-use your own autoloader or require the needed files directly in your code.
+[PSR-4](http://www.php-fig.org/psr/psr-4/) standard, so you can also use your
+own autoloader or require the needed files directly in your code.
 
-### Development install
+## Usage
 
-If you would like to contribute to this project or run the unit tests on within
-your own environment you will need to install the development dependencies, in
-this case that means [PHPUnit](https://phpunit.de/). If you clone the repo and
-run `composer install` from within the repo, this will also grab PHPUnit and all
-its dependencies for you. If you only need the autoloader installed, then you
-can always specify to Composer not to run in development mode, e.g. `composer
-install --no-dev`.
+First obtain the appropriate keys for the type of reCAPTCHA you wish to
+integrate for v2 at https://www.google.com/recaptcha/admin or v3 at
+https://g.co/recaptcha/v3.
 
-*Note:* These dependencies are only required for development, there's no
-requirement for them to be included in your production code.
+Then follow the [integration guide on the developer
+site](https://developers.google.com/recaptcha/intro) to add the reCAPTCHA
+functionality into your frontend.
 
-## Usage
+This library comes in when you need to verify the user's response. On the PHP
+side you need the response from the reCAPTCHA service and secret key from your
+credentials. Instantiate the `ReCaptcha` class with your secret key, specify any
+additional validation rules, and then call `verify()` with the reCAPTCHA
+response and user's IP address. For example:
 
-First, register keys for your site at https://www.google.com/recaptcha/admin
+```php
+<?php
+$recaptcha = new \ReCaptcha\ReCaptcha($secret);
+$resp = $recaptcha->setExpectedHostname('recaptcha-demo.appspot.com')
+                  ->verify($gRecaptchaResponse, $remoteIp);
+if ($resp->isSuccess()) {
+    // Verified!
+} else {
+    $errors = $resp->getErrorCodes();
+}
+```
+
+The following methods are available:
+
+- `setExpectedHostname($hostname)`: ensures the hostname matches. You must do
+  this if you have disabled "Domain/Package Name Validation" for your
+  credentials.
+- `setExpectedApkPackageName($apkPackageName)`: if you're verifying a response
+  from an Android app. Again, you must do this if you have disabled
+  "Domain/Package Name Validation" for your credentials.
+- `setExpectedAction($action)`: ensures the action matches for the v3 API.
+- `setScoreThreshold($threshold)`: set a score theshold for responses from the
+  v3 API
+- `setChallengeTimeout($timeoutSeconds)`: set a timeout between the user passing
+  the reCAPTCHA and your server processing it.
+
+Each of the `set`\*`()` methods return the `ReCaptcha` instance so you can chain
+them together. For example:
 
-When your app receives a form submission containing the `g-recaptcha-response`
-field, you can verify it using:
 ```php
 <?php
 $recaptcha = new \ReCaptcha\ReCaptcha($secret);
-$resp = $recaptcha->verify($gRecaptchaResponse, $remoteIp);
+$resp = $recaptcha->setExpectedHostname('recaptcha-demo.appspot.com')
+                  ->setExpectedAction('homepage')
+                  ->setScoreThreshold(0.5)
+                  ->verify($gRecaptchaResponse, $remoteIp);
+
 if ($resp->isSuccess()) {
-    // verified!
-    // if Domain Name Validation turned off don't forget to check hostname field
-    // if($resp->getHostName() === $_SERVER['SERVER_NAME']) {  }
+    // Verified!
 } else {
     $errors = $resp->getErrorCodes();
 }
 ```
 
-You can see an end-to-end working example in
-[examples/example-captcha.php](examples/example-captcha.php)
+You can find the constants for the libraries error codes in the `ReCaptcha`
+class constants, e.g. `ReCaptcha::E_HOSTNAME_MISMATCH`
+
+For more details on usage and structure, see [ARCHITECTURE](ARCHITECTURE.md).
 
-## Upgrading
+### Examples
 
-### From 1.0.0
+You can see examples of each reCAPTCHA type in [examples/](examples/). You can
+run the examples locally by using the Composer script:
+
+```sh
+composer run-script serve-examples
+```
 
-The previous version of this client is still available on the `1.0.0` tag [in
-this repo](https://github.com/google/recaptcha/tree/1.0.0) but it is purely for
-reference and will not receive any updates.
+This makes use of the in-built PHP dev server to host the examples at
+http://localhost:8080/
 
-The major changes in 1.1.0 are:
-* installation now via Composer;
-* class loading also via Composer;
-* classes now namespaced;
-* old method call was `$rc->verifyResponse($remoteIp, $response)`, new call is
-  `$rc->verify($response, $remoteIp)`
+These are also hosted on Google AppEngine Flexible environment at
+https://recaptcha-demo.appspot.com/. This is configured by
+[`app.yaml`](./app.yaml) which you can also use to [deploy to your own AppEngine
+project](https://cloud.google.com/appengine/docs/flexible/php/download).
 
 ## Contributing
 
-We accept contributions via GitHub Pull Requests, but all contributors need to
-be covered by the standard Google Contributor License Agreement. You can find
-instructions for this in [CONTRIBUTING](CONTRIBUTING.md)
+No one ever has enough engineers, so we're very happy to accept contributions
+via Pull Requests. For details, see [CONTRIBUTING](CONTRIBUTING.md)

app.yaml

@@ -0,0 +1,8 @@
+runtime: php
+env: flex
+
+skip_files:
+- tests
+
+runtime_config:
+  document_root: examples