Implementing proposed Psr\Captcha

Author: phpfui

composer.json

@@ -19,7 +19,7 @@
         "phpstan/phpstan": "^2.1"
     },
     "autoload": {
-        "psr-4": {"ReCaptcha\\": "src/ReCaptcha"}
+        "psr-4": {"ReCaptcha\\": "src/ReCaptcha", "Psr\\Captcha\\": "src/Captcha"}
     },
     "autoload-dev": {
          "psr-4": {"ReCaptcha\\": "tests/ReCaptcha/"}

src/Captcha/CaptchaException.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Psr\Captcha;
+
+/**
+ * MUST be thrown from CaptchaVerifierInterface methods if Captcha test itself cannot be passed due to any reason that is not user-related - network problems, incorrect secret token, unable to parse request-response, etc.
+ * MUST NOT be thrown if CAPTCHA was actually performed validation - even if it failed - instead CaptchaVerifierInterface MUST return CaptchaResponseInterface which ::isSuccess() method MUST return false
+ */
+class CaptchaException extends \RuntimeException
+{
+}

src/Captcha/CaptchaResponseInterface.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace Psr\Captcha;
+
+/**
+ * Interface of the object that CaptchaVerifierInterface MUST return on ::verify() method.
+ * MUST contain enough information to consistently say whether user successfully passed Captcha or not.
+ * SHOULD contain actual user's SCORING
+ * MAY contain additional information (e.g., gathered from it's captcha-vendor service's verification endpoint) (i.e. message, errors, etc.)
+ */
+interface CaptchaResponseInterface
+{
+  /**
+   * MUST return true/false depends on whether verification was successful or not (is user a bot or not).
+   *
+   * @return bool
+   */
+  public function isSuccess(): bool;
+}

src/Captcha/CaptchaVerifierInterface.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Psr\Captcha;
+
+/**
+ * Interface of Captcha verification service itself.
+ * MUST decide whether user passed the Captcha or not and return corresponding response.
+ * SHOULD contain method to configure SCORING threshold (if applicable by PROVIDER)
+ * SHOULD throw a CaptchaException as soon as possible if appears any non-user related error that prevents correct Captcha solving (e.g. network problems, incorrect secret token, e.g.)
+ */
+interface CaptchaVerifierInterface
+{
+  /**
+   * Verifies client token and decides whether verification was successful or not (is user a bot or not).
+   *
+   * @param string $token
+   *
+   * @throws CaptchaException if Captcha cannot be validated because of non-user problems (e.g. due to network problems, incorrect secret token, etc.)
+   * @return CaptchaResponseInterface
+   */
+  public function verify(string $token): CaptchaResponseInterface;
+}

src/ReCaptcha/ReCaptcha.php

@@ -38,7 +38,7 @@
 /**
  * reCAPTCHA client.
  */
-class ReCaptcha
+class ReCaptcha implements \Psr\Captcha\CaptchaVerifierInterface
 {
     /**
      * Version of this client library.
@@ -123,12 +123,12 @@ class ReCaptcha
      *
      * @param string $secret The shared key between your site and reCAPTCHA.
      * @param ?RequestMethod $requestMethod method used to send the request. Defaults to POST.
-     * @throws \RuntimeException if $secret is invalid
+     * @throws \Psr\Captcha\CaptchaException if $secret is invalid
      */
     public function __construct(private string $secret, private ?RequestMethod $requestMethod = null)
     {
         if (empty($secret)) {
-            throw new \RuntimeException('No secret provided');
+            throw new \Psr\Captcha\CaptchaException('No secret provided');
         }
 
         if (is_null($requestMethod)) {
@@ -141,7 +141,7 @@ public function __construct(private string $secret, private ?RequestMethod $requ
      * 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.
+     * @param ?string $remoteIp The end user's IP address.
      *
      * @return Response Response from the service.
      */

src/ReCaptcha/Response.php

@@ -38,7 +38,7 @@
 /**
  * The response returned from the service.
  */
-class Response
+class Response implements \Psr\Captcha\CaptchaResponseInterface
 {
     /**
      * Build the response from the expected JSON returned by the service.

tests/ReCaptcha/ReCaptchaTest.php

@@ -43,7 +43,7 @@ class ReCaptchaTest extends TestCase
     #[DataProvider('invalidSecretProvider')]
     public function testExceptionThrownOnInvalidSecret($invalid)
     {
-        $this->expectException(\RuntimeException::class);
+        $this->expectException(\Psr\Captcha\CaptchaException::class);
         $rc = new ReCaptcha($invalid);
     }