Merge 10fa8ca into 79ccf65

src/ReCaptcha/ReCaptcha.php

@@ -37,7 +37,7 @@
 /**
  * reCAPTCHA client.
  */
-class ReCaptcha
+class ReCaptcha implements ReCaptchaContract
 {
     /**
      * Version of this client library.
@@ -145,12 +145,7 @@ public function __construct($secret, RequestMethod $requestMethod = null)
     }
 
     /**
-     * Calls the reCAPTCHA siteverify API to verify whether the user passes
-     * CAPTCHA test and additionally runs any specified additional checks
-     *
-     * @param string $response The user response token provided by reCAPTCHA, verifying the user on your site.
-     * @param string $remoteIp The end user's IP address.
-     * @return Response Response from the service.
+     * @inheritDoc
      */
     public function verify($response, $remoteIp = null)
     {
@@ -205,11 +200,7 @@ public function verify($response, $remoteIp = null)
     }
 
     /**
-     * Provide a hostname to match against in verify()
-     * This should be without a protocol or trailing slash, e.g. www.google.com
-     *
-     * @param string $hostname Expected hostname
-     * @return ReCaptcha Current instance for fluent interface
+     * @inheritDoc
      */
     public function setExpectedHostname($hostname)
     {
@@ -218,10 +209,7 @@ public function setExpectedHostname($hostname)
     }
 
     /**
-     * Provide an APK package name to match against in verify()
-     *
-     * @param string $apkPackageName Expected APK package name
-     * @return ReCaptcha Current instance for fluent interface
+     * @inheritDoc
      */
     public function setExpectedApkPackageName($apkPackageName)
     {
@@ -230,11 +218,7 @@ public function setExpectedApkPackageName($apkPackageName)
     }
 
     /**
-     * Provide an action to match against in verify()
-     * This should be set per page.
-     *
-     * @param string $action Expected action
-     * @return ReCaptcha Current instance for fluent interface
+     * @inheritDoc
      */
     public function setExpectedAction($action)
     {
@@ -243,11 +227,7 @@ public function setExpectedAction($action)
     }
 
     /**
-     * Provide a threshold to meet or exceed in verify()
-     * Threshold should be a float between 0 and 1 which will be tested as response >= threshold.
-     *
-     * @param float $threshold Expected threshold
-     * @return ReCaptcha Current instance for fluent interface
+     * @inheritDoc
      */
     public function setScoreThreshold($threshold)
     {
@@ -256,10 +236,7 @@ public function setScoreThreshold($threshold)
     }
 
     /**
-     * Provide a timeout in seconds to test against the challenge timestamp in verify()
-     *
-     * @param int $timeoutSeconds Expected hostname
-     * @return ReCaptcha Current instance for fluent interface
+     * @inheritDoc
      */
     public function setChallengeTimeout($timeoutSeconds)
     {

src/ReCaptcha/ReCaptchaContract.php

@@ -0,0 +1,93 @@
+<?php
+/**
+ * This is a PHP library that handles calling reCAPTCHA.
+ *
+ * BSD 3-Clause License
+ * @copyright (c) 2019, Google Inc.
+ * @link https://www.google.com/recaptcha
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * 1. Redistributions of source code must retain the above copyright notice, this
+ *    list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. Neither the name of the copyright holder nor the names of its
+ *    contributors may be used to endorse or promote products derived from
+ *    this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+ * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+namespace ReCaptcha;
+
+/**
+ * ReCaptcha contract allows dependency inversion. Add this interface
+ * to your own ReCaptcha implementations.
+ */
+interface ReCaptchaContract
+{
+    /**
+     * Verify whether the user passes verification.
+     *
+     * @param string $response The user response token provided by reCAPTCHA, verifying the user on your site.
+     * @param string $remoteIp The end user's IP address.
+     * @return Response Response from the service.
+     */
+    public function verify($response, $remoteIp = null);
+
+    /**
+     * Provide a hostname to match against in verify()
+     *
+     * @param string $hostname Expected hostname
+     * @return ReCaptchaContract Current instance for fluent interface
+     */
+    public function setExpectedHostname($hostname);
+
+    /**
+     * Provide an APK package name to match against in verify()
+     *
+     * @param string $apkPackageName Expected APK package name
+     * @return ReCaptchaContract Current instance for fluent interface
+     */
+    public function setExpectedApkPackageName($apkPackageName);
+
+    /**
+     * Provide an action to match against in verify()
+     * This should be set per page.
+     *
+     * @param string $action Expected action
+     * @return ReCaptchaContract Current instance for fluent interface
+     */
+    public function setExpectedAction($action);
+
+    /**
+     * Provide a threshold to meet or exceed in verify()
+     * Threshold should be a float between 0 and 1 which will be tested as response >= threshold.
+     *
+     * @param float $threshold Expected threshold
+     * @return ReCaptchaContract Current instance for fluent interface
+     */
+    public function setScoreThreshold($threshold);
+
+    /**
+     * Provide a timeout in seconds to test against the challenge timestamp in verify()
+     *
+     * @param int $timeoutSeconds Expected hostname
+     * @return ReCaptchaContract Current instance for fluent interface
+     */
+    public function setChallengeTimeout($timeoutSeconds);
+}