Search by

rafalmasiarek / dashboard-kit-addon-recaptcha

rafalmasiarek

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

Statistics

Installs: 40

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 3

v3.0.4 2026-10-07 12:41 UTC

README

THIS REPOSITORY IS NO LONGER MAINTAINED

Packagist Version Total Downloads PHP License

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

License: BUSL-1.1

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

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()

source

public function increment(): int

Increment the failure counter for the current session.

Returns: int — Updated counter value.

count()

FailedLoginTracker count()

source

public function count(): int

Return the current failure count for the session.

Returns: int

reset()

FailedLoginTracker reset()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

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.