[Summary view] [Print] [Text view]

   1  # Architecture
   2  
   3  The general pattern of usage is to instantiate the `ReCaptcha` class with your
   4  secret key, specify any additional validation rules, and then call `verify()`
   5  with the reCAPTCHA response and user's IP address. For example:
   6  
   7  ```php
   8  <?php
   9  $recaptcha = new \ReCaptcha\ReCaptcha($secret);
  10  $resp = $recaptcha->setExpectedHostname('recaptcha-demo.appspot.com')
  11                    ->verify($gRecaptchaResponse, $remoteIp);
  12  if ($resp->isSuccess()) {
  13      // Verified!
  14  } else {
  15      $errors = $resp->getErrorCodes();
  16  }
  17  ```
  18  
  19  By default, this will use the
  20  [`stream_context_create()`](https://secure.php.net/stream_context_create) and
  21  [`file_get_contents()`](https://secure.php.net/file_get_contents) to make a POST
  22  request to the reCAPTCHA service. This is handled by the
  23  [`RequestMethod\Post`](./src/ReCaptcha/RequestMethod/Post.php) class.
  24  
  25  ## Alternate request methods
  26  
  27  You may need to use other methods for making requests in your environment. The
  28  [`ReCaptcha`](./src/ReCaptcha/ReCaptcha.php) class allows an optional
  29  [`RequestMethod`](./src/ReCaptcha/RequestMethod.php) instance to configure this.
  30  For example, if you want to use [cURL](https://secure.php.net/curl) instead you
  31  can do this:
  32  
  33  ```php
  34  <?php
  35  $recaptcha = new \ReCaptcha\ReCaptcha($secret, new \ReCaptcha\RequestMethod\CurlPost());
  36  ```
  37  
  38  Alternatively, you can also use a [socket](https://secure.php.net/fsockopen):
  39  
  40  ```php
  41  <?php
  42  $recaptcha = new \ReCaptcha\ReCaptcha($secret, new \ReCaptcha\RequestMethod\SocketPost());
  43  ```
  44  
  45  ## Adding new request methods
  46  
  47  Create a class that implements the
  48  [`RequestMethod`](./src/ReCaptcha/RequestMethod.php) interface. The convention
  49  is to name this class `RequestMethod\`_MethodType_`Post` and create a separate
  50  `RequestMethod\`_MethodType_ class that wraps just the calls to the network
  51  calls themselves. This means that the `RequestMethod\`_MethodType_`Post` can be
  52  unit tested by passing in a mock. Take a look at
  53  [`RequestMethod\CurlPost`](./src/ReCaptcha/RequestMethod/CurlPost.php) and
  54  [`RequestMethod\Curl`](./src/ReCaptcha/RequestMethod/Curl.php) with the matching
  55  [`RequestMethod/CurlPostTest`](./tests/ReCaptcha/RequestMethod/CurlPostTest.php)
  56  to see this pattern in action.
  57  
  58  ### Error conventions
  59  
  60  The client returns the response as provided by the reCAPTCHA services augmented
  61  with additional error codes based on the client's checks. When adding a new
  62  [`RequestMethod`](./src/ReCaptcha/RequestMethod.php) ensure that it returns the
  63  `ReCaptcha::E_CONNECTION_FAILED` and `ReCaptcha::E_BAD_RESPONSE` where
  64  appropriate.