rafalmasiarek / dashboard-kit-addon-recaptcha
Google reCAPTCHA v2 addon for rafalmasiarek/dashboard-kit. Injects captcha into login and register forms with always or x-failed-attempts modes. DEPRECATED: no longer developed, superseded by rafalmasiarek/dashboard-kit-addon-captcha -- use that package instead.
Package info
github.com/rafalmasiarek/php-dashboard-kit-addon-recaptcha
pkg:composer/rafalmasiarek/dashboard-kit-addon-recaptcha
Requires
- php: >=8.2
- rafalmasiarek/dashboard-kit: ^4.0 || ^5.0
- rafalmasiarek/dns-resolver: ^0.1.0 || ^0.2.0
- rafalmasiarek/http-client: ^1.0.1 || ^2.0
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-17 23:36:55 UTC
README
THIS REPOSITORY IS NO LONGER MAINTAINED
This repository is no longer developed.
Superseded by rafalmasiarek/dashboard-kit-addon-captcha, which covers reCAPTCHA (v2/v3), Cloudflare Turnstile, and hCaptcha through one generalized integration. Please migrate to that package — it is the actively developed replacement.
Google reCAPTCHA v2 addon for rafalmasiarek/dashboard-kit.
Injects the captcha widget into login and register forms via the FormSlotRegistry extension point. Server-side verification uses the before_login / before_register hook chain.
License
Business Source License 1.1.
Source available; commercial use restricted until 2099-01-01.
See LICENSE for full details.
For alternative licensing, contact us.
Authors
Requirements
- PHP 8.2+
rafalmasiarek/dashboard-kit: *- Google reCAPTCHA v2 site key and secret key
Installation
composer require rafalmasiarek/dashboard-kit-addon-recaptcha
Usage
Via Dashboard::create() config (recommended)
Pass config under the recaptcha key in Dashboard::create(). No arguments needed at the call site:
$dashboard = Dashboard::create(__DIR__ . '/../', [ 'recaptcha' => [ 'site_key' => $_ENV['RECAPTCHA_SITE_KEY'], 'secret_key' => $_ENV['RECAPTCHA_SECRET_KEY'], 'login' => ['mode' => 'x_failed', 'threshold' => 3], 'register' => true, ], ]); RecaptchaAddon::register($dashboard->getApp(), $dashboard->getContainer());
Inline config
Pass config directly to register(). Takes precedence over app.config['recaptcha'] when both are set.
RecaptchaAddon::register($dashboard->getApp(), $dashboard->getContainer(), [ 'site_key' => 'your-site-key', 'secret_key' => 'your-secret-key', 'login' => ['mode' => 'x_failed', 'threshold' => 3], 'register' => true, ]);
Configuration
| Key | Type | Description |
|---|---|---|
site_key |
string | reCAPTCHA v2 site key (required) |
secret_key |
string | reCAPTCHA v2 secret key (required) |
login |
array|false | Login form config. false disables captcha on login. |
login.mode |
'always'|'x_failed' |
always — show on every login attempt. x_failed — show only after N consecutive failures. |
login.threshold |
int | Number of failures before captcha appears (x_failed mode). Default: 3. |
register |
bool | Whether to show captcha on the register form. Default: false. |
Modes
always
The captcha widget is rendered on every visit to /login. The token is verified on every POST.
'login' => ['mode' => 'always'],
x_failed
The captcha is hidden until the user has failed threshold consecutive login attempts within the same browser session. After the threshold is reached, the captcha appears and its token is verified on every subsequent attempt. A successful login resets the counter.
'login' => ['mode' => 'x_failed', 'threshold' => 3],
Frontend submit blocker
When the captcha widget is rendered, the form's submit button is disabled immediately on page load — before the reCAPTCHA API script even loads. The button is re-enabled only after the challenge is solved and disabled again if the token expires.
This prevents the backend from being hit with unanswered CAPTCHA requests. Server-side verification via before_login / before_register remains the authoritative check — the frontend blocker is a UX layer only.
In x_failed mode the blocker appears together with the widget, so the button is not affected until the threshold is reached.
Testing
Google provides permanent test keys that always pass verification:
| Key | Value |
|---|---|
| Site key | 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI |
| Secret key | 6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe |
The captcha widget renders with a "This is a test" watermark when using test keys.
Index
Classes
FailedLoginTracker—rafalmasiarek\DashboardKitRecaptchaRecaptchaAddon—rafalmasiarek\DashboardKitRecaptchaRecaptchaVerifier—rafalmasiarek\DashboardKitRecaptcha
FailedLoginTracker
final class — rafalmasiarek\DashboardKitRecaptcha\FailedLoginTracker · source
Tracks failed login attempts in the PHP session for the current browser session. Used by RecaptchaAddon to determine whether the reCAPTCHA widget should be displayed and verified when mode is set to 'x_failed'. The session must already be started before any method is called. AuthKit's PhpSessionTransport::initialize() guarantees this because Auth::isLoggedIn() — invoked at the top of AuthController::login() — triggers the transport initialisation.
| Method | Visibility | Returns | Summary |
|---|---|---|---|
increment() |
public | int |
Increment the failure counter for the current session. |
count() |
public | int |
Return the current failure count for the session. |
reset() |
public | void |
Reset the failure counter, e.g. on successful login. |
increment()
FailedLoginTracker increment()
public function increment(): int
Increment the failure counter for the current session.
Returns: int — Updated counter value.
count()
FailedLoginTracker count()
public function count(): int
Return the current failure count for the session.
Returns: int
reset()
FailedLoginTracker reset()
public function reset(): void
Reset the failure counter, e.g. on successful login.
RecaptchaAddon
final class — rafalmasiarek\DashboardKitRecaptcha\RecaptchaAddon · source
Wires Google reCAPTCHA (v2 checkbox or v3 invisible) into dashboard-kit login and register forms.
| Method | Visibility | Returns | Summary |
|---|---|---|---|
register() |
public static | void |
Register the reCAPTCHA addon with the given application and container. |
wireLogin() |
private static | void |
Wire reCAPTCHA into the login form. Registers form slots and wraps the before_login hook to verify the token. In x_failed mode (v2 only), the captcha is shown and verified only after the threshold of consecutive failed attempts is reached within the current session. v3 is invisible and, having no widget to show/hide, always runs. |
scripts() |
private static | string |
Returns the reCAPTCHA API script tag and the submit-button blocker. The blocker disables the form's submit button immediately on page load and re-enables it only after the reCAPTCHA challenge is solved. The button is disabled again when the token expires. |
widgetMarkup() |
private static | string |
Widget markup for the form_fields slot. v2 renders the visible checkbox div; v3 has no widget — only a hidden field the script fills in right before submit. |
v2Scripts() |
private static | string |
v2 checkbox scripts: loads the API and blocks submit until solved. |
v3Scripts() |
private static | string |
v3 invisible scripts: intercepts submit, fetches a token, fills the hidden field, then resubmits via the raw DOM submit() (which, unlike requestSubmit(), does not re-fire the 'submit' event — no loop guard needed). |
minifyInlineJs() |
private static | string |
Collapses a multi-line JavaScript snippet to a single line. Trims each line, collapses internal whitespace, drops blank lines. Safe only for simple scripts — no regex literals, no template strings. |
wireRegister() |
private static | void |
Wire reCAPTCHA into the register form. Captcha is always shown on the register form when this method is called. |
register()
RecaptchaAddon register()
public static function register(App $app, ContainerInterface $container, array $config): void
Register the reCAPTCHA addon with the given application and container.
| Param | Type | Description |
|---|---|---|
$app |
App |
Slim application instance. |
$container |
ContainerInterface |
PHP-DI container. |
$config |
array<string, mixed> |
Addon configuration: site_key, secret_key, version ('v2'|'v3', default 'v2'), login, register. login/register may be true/false or an array with 'mode'/'threshold' (v2, login only), 'min_score' and 'action' (v3 only, both optional). |
wireLogin()
RecaptchaAddon wireLogin()
private static function wireLogin(ContainerInterface $container, RecaptchaVerifier $verifier, FailedLoginTracker $tracker, string $siteKey, string $version, array $loginConfig): void
Wire reCAPTCHA into the login form. Registers form slots and wraps the before_login hook to verify the token. In x_failed mode (v2 only), the captcha is shown and verified only after the threshold of consecutive failed attempts is reached within the current session. v3 is invisible and, having no widget to show/hide, always runs.
| Param | Type | Description |
|---|---|---|
$container |
ContainerInterface |
— |
$verifier |
RecaptchaVerifier |
— |
$tracker |
FailedLoginTracker |
— |
$siteKey |
string |
— |
$version |
string |
'v2' or 'v3'. |
$loginConfig |
array<string, mixed> |
v2: 'mode', 'threshold'. v3: 'min_score', 'action'. |
scripts()
RecaptchaAddon scripts()
private static function scripts(string $version, string $siteKey, string $action): string
Returns the reCAPTCHA API script tag and the submit-button blocker. The blocker disables the form's submit button immediately on page load and re-enables it only after the reCAPTCHA challenge is solved. The button is disabled again when the token expires.
| Param | Type | Description |
|---|---|---|
$version |
string |
'v2' or 'v3'. |
$siteKey |
string |
Site key (only needed by v3, embedded in the execute() call). |
$action |
string |
v3 only: action name passed to grecaptcha.execute(). |
Returns: string — HTML to inject into the scripts slot.
widgetMarkup()
RecaptchaAddon widgetMarkup()
private static function widgetMarkup(string $version, string $siteKey, string $action): string
Widget markup for the form_fields slot. v2 renders the visible checkbox div; v3 has no widget — only a hidden field the script fills in right before submit.
| Param | Type | Description |
|---|---|---|
$version |
string |
'v2' or 'v3'. |
$siteKey |
string |
Site key (only used by the v2 checkbox's data-sitekey). |
$action |
string |
Unused for v2; kept for a uniform call signature. |
Returns: string — HTML to inject into the form_fields slot.
v2Scripts()
RecaptchaAddon v2Scripts()
private static function v2Scripts(): string
v2 checkbox scripts: loads the API and blocks submit until solved.
Returns: string — HTML to inject into the scripts slot.
v3Scripts()
RecaptchaAddon v3Scripts()
private static function v3Scripts(string $siteKey, string $action): string
v3 invisible scripts: intercepts submit, fetches a token, fills the hidden field, then resubmits via the raw DOM submit() (which, unlike requestSubmit(), does not re-fire the 'submit' event — no loop guard needed).
| Param | Type | Description |
|---|---|---|
$siteKey |
string |
Site key passed to the render= API and to execute(). |
$action |
string |
Action name passed to grecaptcha.execute(). |
Returns: string — HTML to inject into the scripts slot.
minifyInlineJs()
RecaptchaAddon minifyInlineJs()
private static function minifyInlineJs(string $js): string
Collapses a multi-line JavaScript snippet to a single line. Trims each line, collapses internal whitespace, drops blank lines. Safe only for simple scripts — no regex literals, no template strings.
| Param | Type | Description |
|---|---|---|
$js |
string |
Multi-line JS source. |
Returns: string — Single-line output.
wireRegister()
RecaptchaAddon wireRegister()
private static function wireRegister(ContainerInterface $container, RecaptchaVerifier $verifier, string $siteKey, string $version, array $registerConfig): void
Wire reCAPTCHA into the register form. Captcha is always shown on the register form when this method is called.
| Param | Type | Description |
|---|---|---|
$container |
ContainerInterface |
— |
$verifier |
RecaptchaVerifier |
— |
$siteKey |
string |
— |
$version |
string |
'v2' or 'v3'. |
$registerConfig |
array<string, mixed> |
v3 only: 'min_score', 'action'. |
RecaptchaVerifier
final class — rafalmasiarek\DashboardKitRecaptcha\RecaptchaVerifier · source
Verifies a Google reCAPTCHA v2 or v3 response token against the siteverify API.
Depends on: HttpClientInterface
| Method | Visibility | Returns | Summary |
|---|---|---|---|
__construct() |
public | — | — |
verify() |
public | bool |
Verify a g-recaptcha-response token from a form submission. $minScore and $expectedAction only apply to v3 tokens — siteverify's response includes 'score' and 'action' for those; both checks are skipped (treated as passing) when the corresponding field is absent, so v2 tokens are unaffected. |
__construct()
RecaptchaVerifier __construct()
public function __construct(HttpClientInterface $http, string $secretKey)
| Param | Type | Description |
|---|---|---|
$http |
HttpClientInterface |
Client used to call the siteverify API. |
$secretKey |
string |
reCAPTCHA secret key from the Google console. |
verify()
RecaptchaVerifier verify()
public function verify(string $token, string $remoteIp, ?float $minScore, ?string $expectedAction): bool
Verify a g-recaptcha-response token from a form submission. $minScore and $expectedAction only apply to v3 tokens — siteverify's response includes 'score' and 'action' for those; both checks are skipped (treated as passing) when the corresponding field is absent, so v2 tokens are unaffected.
| Param | Type | Description |
|---|---|---|
$token |
string |
Value of the g-recaptcha-response POST field. |
$remoteIp |
string |
Client IP address for additional validation. |
$minScore |
float|null |
v3 only: minimum accepted score. Null = do not check. |
$expectedAction |
string|null |
v3 only: expected 'action' value. Null = do not check. |
Returns: bool — True when Google confirms the token is valid.