New PSR for standartizing CAPTCHA (CaptchaInterface)

[LeTraceurSnork]

Here's a proposal of new PSR for standartizing CAPTCHAs to one interface
Continuation of this thread: https://discord.com/channels/788815898948665366/788816084383694848/1379332512886689812

TL;DR:
Recently we've faced with a problem that government forbids to gather data abroad and we urgently need to switch Google ReCaptcha to other solutions, but the thing is that since those solutions doesn't have common interface yet, the codebase needs to be refactored, which isn't good - the task in a nutshell is just "switch vendors"

UPD1: demo-repository was created https://github.com/LeTraceurSnork/psr-captcha-verifier
UPD2: Working Group can communicate now via Discord-channel (https://discord.com/channels/788815898948665366/1386802002599739443)

[jaapio]

I do not really see why we need a psr for this. An interface can always be used by any developer in any application.

The problem of recaptcha is a very specific implementation to validate humans interacting with your website. While there are other solutions.

Can you explain why you think this should be a standard?

[LeTraceurSnork]

@jaapio

Can you explain why you think this should be a standard?
I'll try in examples

So, for example, I have a Google ReCaptcha on my website, lets say I installed it via composer from corresponding repository. Let's omit frontend integration and look at the backend, we have smth like this:

class FormSubmitService
{
    private $recaptcha;

    public function __construct(\ReCaptcha\ReCaptcha $recaptcha)
    {
        $this->recaptcha = $recaptcha;
    }

    public function submitForm(CustomRequest $request): CustomResponse
    {
        $token = $request->get('g-recaptcha-response');
        
        $response = $this->recaptcha->verify($token);
                                    
        if (!$response->isSuccess()) {
            return new CustomResponse('Recaptcha failed!');
        }
        
        // ... continue to submit fom
    }
}

//...

$recaptcha = new \ReCaptcha\ReCaptcha('my_secret_token');
$formSubmitService = new FormSubmitService($recaptcha);
$formSubmitService->submitForm($incomeCustomRequest);

So, what happens if we at some moment switch to another Captcha vendor (another SDK)? We immediately lose the \ReCaptcha\ReCaptcha class, __construct() fails with Type error, DI ruined. At this point we want to rely on some interface like this:

public function __construct(CaptchaInterface $captcha)
{
    $this->captcha= $captcha;
}

because in this scenario we can pass:

$recaptcha = new \ReCaptcha\ReCaptcha('my_secret_token');
$hcaptcha = new \HCaptcha\HCaptcha('my_secret_token');
$mcaptcha= new \MCaptcha\MCaptcha('my_secret_token');
$cloudflareTurnstile= new \Cloudflare\Turnstile('my_secret_token');
$smartCaptcha= new \Yandex\SmartCaptcha('my_secret_token');
$formSubmitService = new FormSubmitService($recaptcha);
$formSubmitService2 = new FormSubmitService($hcaptcha);
$formSubmitService3 = new FormSubmitService($mcaptcha);
$formSubmitService4 = new FormSubmitService($cloudflareTurnstile);
$formSubmitService5 = new FormSubmitService($smartCaptcha);

Yes, we will need an additional configuration when constructing the Captcha object itself, but inside the form handler there will be no changes, 'cause all of the above will be able to say true/false $response->isSuccess(), so the switching between providers will be much easier

[KorvinSzanto]

I'm still on the fence about whether this deserves a PSR or not, I think that's going to depend on what kind of buy-in we can get from the projects that we'd expect to benefit from this.

There are some additional things that come with the request that captcha services typically either require or optionally allow like the visitors IP address. It'd be better in my opinion to depend on PSR-7 and pass the entire RequestInterface implementation to the verify method so that the implementation can decide what to gather.
Probably also would benefit from exceptions for the different known exceptional cases like a PSR-6-esque InvalidArgumentException and maybe a ValidationRequestErrorException or similar so that folks can adequately handle exceptions without needing to know what underlying tools are being used by the implementation.

[KorvinSzanto]

Whoops, fat fingered the close button.

[LeTraceurSnork]

@KorvinSzanto since all of the most popular Captchas (and, I guess, all of the external Captchas) requires secret token to connect to their validation routes, I guess it would benefit to add InvalidArgumentException to CaptchaInterface::verify() to handle incorrect secret token cases.
Not quite sure about ValidationRequestErrorException tho, but I guess smth like that can be added to CaptchaInterface::verify() as well, but I'm not quite sure to what scenario. Captcha service did not respond? Respond with not 2** (404, 500, etc.)? Respond with 200 but "Captcha not passed"? 🤔

[mbeccati]

Have you already gathered some consensus between the developers of the major captcha libraries in PHP?

[KorvinSzanto]

@KorvinSzanto since all of the most popular Captchas (and, I guess, all of the external Captchas) requires secret token to connect to their validation routes, I guess it would benefit to add InvalidArgumentException to CaptchaInterface::verify() to handle incorrect secret token cases. Not quite sure about ValidationRequestErrorException tho, but I guess smth like that can be added to CaptchaInterface::verify() as well, but I'm not quite sure to what scenario. Captcha service did not respond? Respond with not 2** (404, 500, etc.)? Respond with 200 but "Captcha not passed"? 🤔

The exceptions would be used for exceptional cases that represent neither pass nor fail, for example:

• The provided request to validate includes multiple captcha tokens, or no token at all
• The implementation sends an http request that fails
• The implementation gets a response that can't be parsed

Without defined exceptions, all of these cases would throw implementation-specific exceptions like a guzzle exception or a recaptcha sdk exception and would require the consumer to know the implementation to properly catch exceptions.

So an implementation would do something like:

try {
    $response = $guzzle->send($validationRequest);
    $isValid = $this->validateResponse($response);
} catch (GuzzleException $e) {
    throw new ImplementationSpecificValidationRequestErrorException('Failed to send validation request', $e);
} catch (ValidationResponseException $e) {
    throw new ImplementationSpecificValidationRequestErrorException('Invalid validation response', $e);
}

and a consumer can avoid knowing that guzzle is in use at all and do:

try {
    $isValid = $captcha->validate($whatever);
} catch (\Psr\Captcha\ValidationRequestErrorException) {
    // Show user "We're having trouble validating your request, please try again in a few minutes"
} catch (\Psr\Captcha\InvalidArgumentException) {
    // Show user "Invalid request, please try again"
}

if (!$isValid) {
    // Show user "Invalid captcha, please try again"
}

[LeTraceurSnork]

Have you already gathered some consensus between the developers of the major captcha libraries in PHP?

@mbeccati
Unfortunately, I did not, 'cause neither Google, hCaptcha, Yandex, nor their core developers in person did not respond to an invitation 😕
I will continue my attempts tho, now it is more convenient with a PR opened

@KorvinSzanto CaptchaException added, seems reasonable. Feel free to open review threads on those interfaces please 🙂

[garak]

Sadly, the Google recaptcha PHP repo is dead.
An issue for PHP 8.4 deprecation has been open for months, with no feedback. The last commit dates back to February 2023.

[samdark]

Overall, I like the idea. The problem domain, indeed, is pretty clear so could be standardized.

[samdark]

Why is it an interface and not a bool?

[LeTraceurSnork]

You mean, why CaptchaInterface::verify() returns that instead of a bool? If yes, then answer is - 'cause you might want to implement additional methods to specific CaptchaResponse classes, like getScore(), getHost() (for instance, those fields implemented by Google ReCaptcha, hCaptcha, SmartCaptcha) or similar - to extend response data

[samdark]

Should be mentioned in meta-document.

[LeTraceurSnork]

mentioned it in captcha-meta.md (added meta-document)

[samdark]

I think there might be a need for challenge(string $token): string method which, given a token, generates the challenge for the user to solve.

[LeTraceurSnork]

Idk what did you mean by this, probably CaptchaInterface needs to be renamed to CaptchaVerifierInterface, 'cause that is its purpose - to verify that passed token is valid. But idk what else can be retrieved from $token, especially in string. Do you mean challenge is frontend rendered I am not a robot checkbox with traffic lights? If so, i'm not sure that service should interact with it - it's just a verifier

[samdark]

Well, for example, given a token that is 24, challenge might be 20+4 or something like that.

[LeTraceurSnork]

Well, that interface is not quite for that purpose, but rather to verify already solved captcha task by its token using some external (or even internal, it doesnt actually matter) captcha service. Roughly, it's an interface to build SDK on

[samdark]

I see. Makes sense.

[samdark]

Here's Yii2 implementation: https://github.com/yiisoft/yii2/tree/master/framework/captcha

[JoshuaBehrens]

Here is Shopware 6 implementation https://github.com/shopware/shopware/tree/e4c3f565857f8e6c53d3c8e35f6b00dfd0eb3f73/src/Storefront/Framework/Captcha and Shopware 5 implementation https://github.com/shopware5/shopware/tree/8779bb0fc2cff04bb92dbba8ea5522263a71ab48/engine/Shopware/Components/Captcha

[LeTraceurSnork]

Here is Shopware 6 implementation https://github.com/shopware/shopware/tree/e4c3f565857f8e6c53d3c8e35f6b00dfd0eb3f73/src/Storefront/Framework/Captcha and Shopware 5 implementation https://github.com/shopware5/shopware/tree/8779bb0fc2cff04bb92dbba8ea5522263a71ab48/engine/Shopware/Components/Captcha

Do you believe that Shopware could use and achieve profit from implementation of this interfaces by recieving more information from responses?

[LeTraceurSnork]

Added demo-repository
https://github.com/LeTraceurSnork/psr-captcha-verifier

[phpfui]

I am the maintainer of a PHP 8.4 compatible version of Google's Recaptcha with about 115K downloads so far and growing.

I think this is an excellent idea for standardization. I would be happy implement any PSR that is agreed to in my fork. But be aware that Google has announced that they will be turning off this version of the service at the end of 2025.

That said, my goal is to allow an easy upgrade path to the newer Google versions of their API with the current package, hopefully with no or minor changes needed by the developer.

[phpfui]

This line should now read:

### 2.1 CaptchaVerifierInterface

Due to the code change.

[LeTraceurSnork]

done

[phpfui]

I have implemented the proposeed Psr\Captcha for Google's ReCaptcha library.

You can find it here in the PSR branch: https://github.com/phpfui/recaptcha

I have not tested it on a live site yet. I will try next week. Something about Friday deploys.

[bytestream]

Maintainer of https://github.com/Gregwar/Captcha. 👍🏼 from me

[LeTraceurSnork]

The administrators of the PHP-FIG community have created a Discord channel for the working group communications of this proposed PSR. I invite everyone interested in participating in the development/support (nominally, we need a working group) to join via the link: https://discord.com/channels/788815898948665366/1386802002599739443

[VincentLanglet]

I feel like Captcha feature is something too specific to be worth a whole personal PSR.
And looking at the interface makes me believe this more.

When looking at:

public function verify(string $token): CaptchaResponseInterface;

I feel like this is not the right signature cause you might need more informations to verify something

Google accepts the IP
If I rely on your interface but call $catch->verify($token, $ip) the benefit is null since I cannot be sure that when I'll change the lib I'll use, the signature will be the same. Using a signature verifiy(string $token, array $context) could help but same, it cannot guarantee the array keys will be the same.

Shopware lib use the request
This does not seems compatible with your interface, and asking the user to parse the request in order to get the token doesn't seems right to me since you're coupling the implementations.

CaptchaResponseInterface is not better, even if the phpdoc is saying the implementation might have extra methods, if I want to be able to switch implementation easily in my project, I have to use only the one provided by the interface. So no score, no error message, and so on...

I believe we'll end with something like

use Psr\Captcha\RequestInterface;
use Psr\Captcha\ResponseInterface;

interface CaptchaInterface
{
    /**
     * @param RequestInterface $request
     *
     * @return ResponseInterface
     *
     * @throws \Psr\Captcha\ExceptionInterface If an error happens while processing the request.
     */
    public function verify(RequestInterface $request): ResponseInterface;
}

when the responseInterface could have

• Score ?float
• isSuccess bool
• and so on

But it seems really close to the PSR 7

[LeTraceurSnork]

I feel like this is not the right signature cause you might need more informations to verify something

@VincentLanglet
Yes, and you can set those information with additional ->set methods or even with constructor params. The main point of this interface is that you can receive this verifier as DI in, say, constructor, and this verifier object is already pumped with all data it needs. Something like:

// Imagine that we're on REST API route controller
$captcha = (new CaptchaVerifier('secret_token', $maybe_http_client))
    ->setIp($maybe_ip)
    ->setTime($maybe_time)
    ->setHost($maybe_host);

$formHandler = new AbstractFormSubmitHandler($captcha);
$formHandler->submit(['token' => $userToken, ...]);

And inside of it we will need to verify this token via specified Captcha, but we do not know what this Captcha is and we do not need to know that, 'cause AbstractFormSubmitHandler::__construct() looks like that:

class AbstractFormSubmitHandler
{
    function __construct(CaptchaVerifierInterface $captcha_verifier){...}
}

And all we do - is just using already pumped object as a Validator, you can say. Token was passed to ::submit(), $captcha_verifier->verify($token) and that's all. This AbstractFormSubmitHandler does not need to be rewritten if Captcha provider is changed, 'cause it does not depend on it.
This approach allows AbstractFormSubmitHandler to remain decoupled from specific captcha implementations, relying only on the interface.

On the other hand, I do understand you concerns about mutable $captcha object, but as I see:

1. Theoretically speaking, it can be immutable (e.g., 100500 constructor params, array $data as param, etc.)
2. All of those params (ip, host, time, smth else) are unnecessary (not required), at least on those Captcha providers that I discovered. You can pass them in addition, but Capctha will pass without them as well
3. This interfaces does not restrict you from using them, because verify() is abstract and setters is omitted from interface

[LeTraceurSnork]

CaptchaResponseInterface is not better, even if the phpdoc is saying the implementation might have extra methods, if I want to be able to switch implementation easily in my project, I have to use only the one provided by the interface. So no score, no error message, and so on

@VincentLanglet on the second part of your message
Thank you for raising an important issue with CaptchaResponseInterface being too minimalistic.

While I believe that having just isSuccess() covers the most basic use case — telling whether the captcha has been passed or not, and keeps the code simple and swappable.
However, as you pointed out, some providers such as ReCaptcha v3 return extra details like 'score', error messages, etc. With the current contract, this data becomes inaccessible if using DI-bound code, unless adding hacks like downcasting or specific type checks, which are not ideal.
A few ways to extend:

• Add a generic getData(): array to expose arbitrary provider details; drawbacks: brittle, no typing. But that's just not good
• Let verify() return a more specific response interface for each implementation, but then consumer code is tied to implementation, so we made a circle
• Include optional getters in the base interface (getScore(), getErrorCodes()), but for many implementations these would need to return null or throw.

For now, the base interface solves the simple validation problem well, but for advanced response handling, it's worth discussing which extensibility pattern (if any) would be preferable — whether as a universal getData(), or a more formal structure.

Thanks for surfacing this; now we're talking and I believe this is what WG should discuss and eventually solve

[phpfui]

I am going to go with what @LeTraceurSnork said. The whole point is to provide a minimal interface that all Capthca systems have to provide. It is minimal, but with some proper code around it, you can easily and quickly swap in another provider. With PHP, that could be configured with a ini file or database entry. The code will work the same. You can then fine tune the new provider if needed.

And as for minimal interfaces, I find the current Container interface also to minimal to be usefull, but that was agreed upon and in use. So I don't think this interface should be rejected simply because it does not account for all use cases. It accounts for enough to be useful and will help standardize Captcha libraries to make them more generic and easy to swap out if needed.

[Crell]

The de facto pattern of several past PSRs has been that the interfaces provide the "read" but not "configure" API. Configure is left up to the particular implementation, and you configure it in advance. The API is just for plugging it in and using it, assuming most of the configuration is already handled before the service gets injected.

(PSR-3 Logging, PSR-11 Containers, PSR-14 Events, PSR-20 Clocks, etc. all take that approach.)

[VincentLanglet]

The last question I have in mind is "Which feature should have a PSR" and which shouldn't.

If we have a CaptchaInterface should we have some

• AuthenticatorInterface
• MailerInterface
• TranslatorInterface
• FeatureToggleInterface
• ...

which are also often used feature ?

Where will be the limit ? (Maybe the answer is none)

[KorvinSzanto]

It's important to keep in mind that not all captchas are built the same. They won't always have a single value to validate, though I concede most do today.

The de facto pattern of several past PSRs has been that the interfaces provide the "read" but not "configure" API. Configure is left up to the particular implementation, and you configure it in advance. The API is just for plugging it in and using it, assuming most of the configuration is already handled before the service gets injected.

To me, captcha input is closer to a cache item than a simple log message. Like the event PSR, we should at the very least accept an object instead of a string. As it sits now, one must know the implementation to successfully use a provided CaptchaInterface and that doesn't jive with the likes of PSR-(3, 11, 14, 20) which can work entirely without knowing the implementation.

In my opinion it'd be better to accept a full PSR-7 request in validate, or in a factory that builds the value to validate. That way I can pass a captcha interface to my controllers and validate the request without needing to cater each controller to properly extract the required information from the request.

[phpfui]

The future of software is interoperable standards that allow things to be mixed and matched and not have vendor lock in. Vendors want lock in, standards prevent that. So yes, we need more standard interfaces, mail and translation would be two good ones to tackle.

We have standards in most industries. Metric bolts for example. JIS (Japanese Industrial Standard) comes to mind. The more we insist on standard interfaces the better off as a PHP community we are in the long run.

[LeTraceurSnork]

The last question I have in mind is "Which feature should have a PSR" and which shouldn't.

@VincentLanglet as I confessed to @samdark recently, I'm an inclusionist, as wikipedians would say 🙂 In my believe, all of your mentioned interfaces may actually be accepted if written properly, reviewed, agreed upon, etc. So, to Where will be the limit ? I would say 'the answer is none'. More PSRs to PSR god 🤩
p.s. isn't TranslatorInterface suggested in PSR-21? 🤔

It's important to keep in mind that not all captchas are built the same. They won't always have a single value to validate, though I concede most do today

@KorvinSzanto yes, absolute most of the Captchas operates token as a string. I did some researches, I've got two different sources that representeed different information about CAPTCHA providers usage percentage, so I've checked following: Google ReCaptcha, Cloudflare Turnstile, hCaptcha, Friendly Captcha, AWS WAF, Yandex SmartCaptcha, GeeTest, Tencent Captcha, Yidun Captcha, MTCaptcha, Altcha, VAPTCHA and KeyCAPTCHA. From all of those (that's more than 99,9% of market) only Altcha verifies something that is not a string - their SDK method accepts array of some data, but even that case is totally fits in presented interface - we with @VincentLanglet discussed it earlier - it can be achieved via mutable objects with ->setters(). Now, after almost all of the known market being analyzed, I guess, even if there is some captcha provider that verifies, say, two tokens simultaneously (and both are required, so we can't go with ->setters()) we can just agree that this one is just too exotic for an interface

To me, captcha input is closer to a cache item than a simple log message. Like the event PSR, we should at the very least accept an object instead of a string. As it sits now, one must know the implementation to successfully use a provided CaptchaInterface

Oh, I see your point. Yes, while we could not have an opportunity to pump the verifier with additional data it needs beforehand (e.g. Verifier needs some data from HttpRequest that being validated right now and the one that actually contains the token), I guess, it is wise to give it an opportunity to do so. But what do you think of an idea to keep the verify($token) as it is, but to add withData(object $data) or withData(array $data) method (or smth like that)?

In my opinion it'd be better to accept a full PSR-7 request in validate

With this being said, I guess, the question "what do we do with Response then" is much more acute for now

@phpfui totally agree with you! More standarts -> less exotic packages that doesn't fits them -> less odd unsupportable legacy