reCAPTCHA Files

Overview

2.1.0 is a backwards-compatible minor release in the 2.x series (PHP >=8.4) introducing immutable with*() builder methods on ReCaptcha, \JsonSerializable support on Response, configurable transport timeouts, ReCaptcha::SITE_VERIFY_URL_ALTERNATIVE, cURL handle connection reuse, unified HTTP status validation across all transports, and validation/security hardening.

What's Changed

• Immutable with*() Builder Methods (ReCaptcha):
• Added withExpectedHostname(), withExpectedApkPackageName(), withExpectedAction(), withScoreThreshold(), and withChallengeTimeout() methods that return a cloned ReCaptcha instance instead of mutating the instance in place—making ReCaptcha safe to share as a singleton in dependency injection containers and persistent worker runtimes (FrankenPHP, RoadRunner, Swoole, Laravel Octane) (#637).
• Response implements \JsonSerializable:
• Implemented \JsonSerializable (jsonSerialize()) on ReCaptcha\Response so response objects can be passed directly to json_encode() (#636).
• Configurable Transport Timeouts & Alternative Global Endpoint:
• Added an optional int $timeout = 60 constructor parameter to CurlPost, Post, and SocketPost, and added CURLOPT_CONNECTTIMEOUT to CurlPost (#636).
• Added ReCaptcha::SITE_VERIFY_URL_ALTERNATIVE (https://www.recaptcha.net/recaptcha/api/siteverify) for environments where www.google.com is not accessible (#636).
• Connection Reuse & Transport Hardening:
• CurlPost now lazily initializes and reuses its CurlHandle across submit() calls for TLS session resumption and HTTP keep-alive (#637).
• Unified HTTP 200 status validation across CurlPost (CURLINFO_HTTP_CODE), Post (http_get_last_response_headers() with ignore_errors), and SocketPost so non-200 HTTP responses consistently return ReCaptcha::E_BAD_RESPONSE (#637).
• SocketPost now loops fwrite() to handle partial TLS socket writes and closes the socket handle cleanly on write failures (#637).
• Security Hardening:
• Added #[\SensitiveParameter] to $secret in ReCaptcha::__construct() and RequestParameters::__construct() to prevent secret exposure in stack traces (#636).
• Hardened examples/ against DOM XSS, added server-side action allowlisting in examples/recaptcha-v3-verify.php, updated CSP connect-src, and added examples/recaptcha-v3-immutable.php (#636, #637).

Bug Fixes

• Fixed setScoreThreshold(0.0) null-coercion bypass when score is omitted (null) from the API response so it properly fails with ReCaptcha::E_SCORE_THRESHOLD_NOT_MET (#637).
• Fixed setChallengeTimeout() failing open when challenge_ts is empty or unparseable; it now fails closed with ReCaptcha::E_CHALLENGE_TIMEOUT (#637).
• Filtered error-codes in Response::fromJson() to ensure only string elements are retained (#636).

Compatibility & Upgrade Guide

• 100% Backwards-Compatible with 2.0.0: Verified via roave/backward-compatibility-check.
• Upgrade via Composer: bash composer update google/recaptcha

Full Changelog: https://github.com/google/recaptcha/compare/2.0.0...2.1.0