Recaptcha Laravel Package

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:

  composer update google/recaptcha
  

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

A lot of clean up, test improvements, and housekeeping but a few potentially breaks to backwards-compatibility for edge cases.

What's Changed

• chore: integrate coveralls-github-action by @rowan-m in https://github.com/google/recaptcha/pull/597
• test: verify default request method fallback by @rowan-m in https://github.com/google/recaptcha/pull/598
• 🎨 Palette: Hide decorative emojis from screen readers in examples by @rowan-m in https://github.com/google/recaptcha/pull/601
• Type hints and more with PHPStan by @rowan-m in https://github.com/google/recaptcha/pull/606
• 🛡️ Sentinel: [MEDIUM] Add timeout to external API calls and fix SSL context by @rowan-m in https://github.com/google/recaptcha/pull/604
• chore: PHP 8.4+ modernization and housekeeping by @SNO7E-G in https://github.com/google/recaptcha/pull/607
• 🧪 Add edge case test for string error-codes in Response by @rowan-m in https://github.com/google/recaptcha/pull/609
• 🧪 Testing Improvement: Add missing edge case test for invalid challenge_ts by @rowan-m in https://github.com/google/recaptcha/pull/608
• 🧪 Add error test for SocketPost connection failure with valid handle by @rowan-m in https://github.com/google/recaptcha/pull/610
• ⚡ Optimize stream reading using stream_get_contents by @rowan-m in https://github.com/google/recaptcha/pull/611
• 🧪 test: edge case tests for string error-codes by @rowan-m in https://github.com/google/recaptcha/pull/615
• 🧪 Add test for overriding siteVerifyUrl in SocketPost by @rowan-m in https://github.com/google/recaptcha/pull/612
• fix: Accept HTTP/1.1 responses in SocketPost to support proxies by @SNO7E-G in https://github.com/google/recaptcha/pull/616
• fix: use strict null checks and explicit property initialization by @SNO7E-G in https://github.com/google/recaptcha/pull/617
• refactor: use readonly classes with promoted constructors for DTOs by @SNO7E-G in https://github.com/google/recaptcha/pull/618
• 🧪 [testing improvement] Add test for case-insensitive hostname matching by @rowan-m in https://github.com/google/recaptcha/pull/622
• fix : prevent reflected XSS by encoding var_export() output by @g0w6y in https://github.com/google/recaptcha/pull/623
• Harden Post fallback TLS verification by @SNO7E-G in https://github.com/google/recaptcha/pull/625

New Contributors

• @SNO7E-G made their first contribution in https://github.com/google/recaptcha/pull/607
• @g0w6y made their first contribution in https://github.com/google/recaptcha/pull/623

Full Changelog: https://github.com/google/recaptcha/compare/1.4.2...1.5

What's Changed

• Remove Travis reference by @rowan-m in https://github.com/google/recaptcha/pull/591
• Define Response::toArray() return type by @rowan-m in https://github.com/google/recaptcha/pull/593
• docs: add note about handling multiple hostnames by @rowan-m in https://github.com/google/recaptcha/pull/594
• Doc updates by @rowan-m in https://github.com/google/recaptcha/pull/592
• feat: default to CurlPost when cURL is available by @rowan-m in https://github.com/google/recaptcha/pull/595

Full Changelog: https://github.com/google/recaptcha/compare/1.4.1...1.4.2

Minor version bump for correct version reporting

Full Changelog: https://github.com/google/recaptcha/compare/1.4.0...1.4.1

What's Changed

• Update to support for PHP 8.4 and 8.5
• Fix .gitattributes by @williamdes in https://github.com/google/recaptcha/pull/587
• Build fixes by @rowan-m in https://github.com/google/recaptcha/pull/588
• Only call curl_close() in PHP < 8 by @jamieburchell in https://github.com/google/recaptcha/pull/583
• Eliminate magic constants usage by @rowan-m in https://github.com/google/recaptcha/pull/589

New Contributors

• @williamdes made their first contribution in https://github.com/google/recaptcha/pull/587
• @jamieburchell made their first contribution in https://github.com/google/recaptcha/pull/583

Full Changelog: https://github.com/google/recaptcha/compare/1.3.1...1.4.0

Update to PHP8 support.