Instructions for examples and architecture

Author: rowan-m

ARCHITECTURE.md

@@ -0,0 +1,55 @@
+# Architecture
+
+The general pattern of usage is to instantiate the
+[`ReCaptcha`](./src/ReCaptcha/ReCaptcha.php) client with your secret key and
+then call `verify()` using the response from the JavaScript reCAPTCHA client.
+
+```php
+<?php
+$recaptcha = new \ReCaptcha\ReCaptcha($secret);
+$resp = $recaptcha->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.

README.md

@@ -17,7 +17,7 @@ and v3.
 
 ## Installation
 
-### Composer
+### Composer (recommended)
 
 Use [Composer](https://getcomposer.org) to install this library from Packagist:
 [`google/recaptcha`](https://packagist.org/packages/google/recaptcha)
@@ -43,7 +43,7 @@ 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);
 ```
 
@@ -77,9 +77,26 @@ if ($resp->isSuccess()) {
 }
 ```
 
-You can see and run examples in [examples/](examples/) and running at
-https://recaptcha-demo.appspot.com/
+For more usage details, see [ARCHITECTURE](ARCHITECTURE.md).
+
+### Examples
+
+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
+```
+
+This makes use of the in-built PHP dev server to host the examples at
+http://localhost:8080/
+
+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 Pull Requests, see [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)