Search by

rafalmasiarek / dashboard-kit-addon-captcha

rafalmasiarek

CAPTCHA addon for rafalmasiarek/dashboard-kit — injects CAPTCHA (reCAPTCHA, Cloudflare Turnstile, hCaptcha, via rafalmasiarek/captcha) into login and register forms, with DB-backed failed-attempt throttling.

Package info

github.com/rafalmasiarek/php-dashboard-kit-addon-captcha

pkg:composer/rafalmasiarek/dashboard-kit-addon-captcha

Statistics

Installs: 15

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 1

v1.0.2 2026-11-01 18:33 UTC

README

CAPTCHA addon for rafalmasiarek/dashboard-kit — injects reCAPTCHA (v2 or v3), Cloudflare Turnstile, or hCaptcha into the login and register forms, verified through rafalmasiarek/captcha.

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

Install

composer require rafalmasiarek/dashboard-kit-addon-captcha

Usage

use rafalmasiarek\DashboardKitCaptcha\CaptchaAddon;

CaptchaAddon::register($app, $container, [
    'provider'   => 'recaptcha_v2', // or 'recaptcha_v3', 'turnstile', 'hcaptcha'
    'site_key'   => $siteKey,
    'secret_key' => $secretKey,
    'login'      => ['mode' => 'x_failed', 'threshold' => 3],
    'register'   => true,
]);

Or via app.config['captcha'] if already bound in the container — register()'s $config argument is merged over it.

Config

Key Scope Meaning
provider both recaptcha_v2 | recaptcha_v3 | turnstile | hcaptcha, or your own CaptchaProviderInterface instance — see below
widget both Required only when provider is a CaptchaProviderInterface instance — the matching CaptchaWidgetDescriptor
site_key, secret_key both Provider credentials — secret_key only required for a built-in shorthand provider; a custom provider already carries its own
login — false (default) to disable, true to always show, or an array (below)
login.mode login 'always' (default) or 'x_failed'
login.threshold login Failed attempts before the widget appears, in x_failed mode (default 3)
login.ttl_seconds login How long a failed-attempt count survives without a fresh failure (default 900)
login.min_score, login.action login reCAPTCHA v3 / hCaptcha Enterprise only — no-op otherwise
register — false (default), true, or an array with min_score/action

An invisible widget (recaptcha_v3) has no checkbox to conditionally show, so x_failed mode has no effect on it — it always runs.

Using a provider this addon doesn't know about

The four shorthand strings are convenience only — CaptchaAddon never needs editing to support a fifth provider, the same extensibility rafalmasiarek/captcha itself offers:

use rafalmasiarek\DashboardKitCaptcha\CaptchaAddon;

CaptchaAddon::register($app, $container, [
    'provider' => new MyCustomProvider($secretKey), // implements CaptchaProviderInterface
    'widget'   => MyCustomProvider::widget(),       // your own CaptchaWidgetDescriptor factory
    'site_key' => $siteKey,
    'login'    => ['mode' => 'x_failed', 'threshold' => 3],
]);

secret_key isn't needed in this form — your provider already carries its own.

Why the failed-attempt counter moved to the database

The superseded addon counted failed logins in $_SESSION. That throttles a human who keeps retyping their password in the same browser tab — it does nothing against an automated attacker, who simply never sends (or keeps) a session cookie between requests; every attempt then starts the counter at zero. FailedAttemptTracker instead keys by the caller's real IP (resolved the same way Captcha itself resolves it — see below), with the PHP session id only as a last-resort fallback when no IP is available at all. The counter is a small table (captcha_failed_attempts), created automatically via dashboard-kit's own schema-sync mechanism, with a configurable TTL so a stale count doesn't linger indefinitely.

IP resolution

If rafalmasiarek\RealIpResolver::class is bound in the container, it's bridged to rafalmasiarek/captcha's RemoteIpProviderInterface via RealIpResolverAdapter and used both as Captcha's default IP source and as the failed-attempt counter's key. Otherwise, both fall back to the same naive $_SERVER['REMOTE_ADDR'] (via rafalmasiarek/captcha's own SystemRemoteIpProvider) — the addon and the library always agree on which IP they're looking at.

Pluggable failed-attempt storage

FailedAttemptStoreInterface (increment()/count()/reset(), TTL-aware) is the seam — FailedAttemptTracker (the default, via dashboard-kit's Model) works with whatever PDO driver the app already configured. A different storage backend (e.g. Redis, for a multi-server deployment without a shared database) can implement the same interface.

Using CaptchaService in your own modules

CaptchaAddon::register() builds one CaptchaService from the app's single ['captcha'] config and binds it in the container — not just for login/register. Any module that wants its own CAPTCHA (a contact form, a newsletter signup, whatever) injects the same service instead of re-deriving provider/widget/site-key wiring itself:

use rafalmasiarek\DashboardKitCaptcha\CaptchaService;

$captchaService = $container->get(CaptchaService::class);

Rendering (give each widget on the page its own instanceId — see rafalmasiarek/captcha's own README for why):

echo $captchaService->widget(instanceId: 'contactform');
echo $captchaService->scripts(action: 'contact_submit', instanceId: 'contactform');

Verifying — captchaFor() returns a real rafalmasiarek\Captcha\Captcha, configured with the addon's provider/site/secret but your own $container label (for log output) and, optionally, your own $expectedAction/$minScore:

$captcha = $captchaService->captchaFor('contactform', expectedAction: 'contact_submit');
$token   = $request->getParsedBody()[$captchaService->tokenFieldName()] ?? '';
$result  = $captcha->verify($token, $remoteIp);

CaptchaService holds no provider-specific knowledge of its own — it's a thin binding of rafalmasiarek/captcha's own Captcha/HtmlHelper/CaptchaWidgetDescriptor to whatever this addon resolved from config, so a module using it gets the exact same behavior (fail-closed score/action checks, the captcha:error client-side event, CSP $nonce support, ...) rafalmasiarek/captcha ^2.0 itself provides — see its own README for the full client-side contract.

Index

Classes

Interfaces

CaptchaAddon

final class — rafalmasiarek\DashboardKitCaptcha\CaptchaAddon · source

Wires CAPTCHA (reCAPTCHA v2/v3, Cloudflare Turnstile, or hCaptcha — via rafalmasiarek/captcha) into dashboard-kit login and register forms, and binds CaptchaService in the container so any OTHER module can render a widget and verify a token too, without re-deriving the same wiring.

Method Visibility Returns Summary
register() public static void Register the CAPTCHA addon with the given application and container.
buildProvider() private static array{CaptchaProviderInterface, CaptchaWidgetDescriptor} Builds the verifier provider + widget descriptor pair for a provider key.
syncSchema() private static void Creates/updates the captcha_failed_attempts table via ModuleSchemaBuilder, the same mechanism and config['schema_defaults'] convention core modules use.
attemptKey() private static string Resolves the throttling key for the current request: the same IP Captcha itself would resolve to (real IP when available, otherwise the naive $_SERVER['REMOTE_ADDR']), falling back to the PHP session id only when no IP information exists at all (e.g. a non-HTTP CLI context).
wireLogin() private static void Wire CAPTCHA into the login form. In x_failed mode, the widget is shown/verified only after $threshold consecutive failed attempts within $ttlSeconds. An invisible widget (reCAPTCHA v3) has no checkbox to conditionally show, so it always runs.
wireRegister() private static void Wire CAPTCHA into the register form. Always shown — there is no x-failed-attempts mode for registration.
register()

CaptchaAddon register()

source

public static function register(App $app, ContainerInterface $container, array $config): void

Register the CAPTCHA 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: 'provider' — either a built-in shorthand string ('recaptcha_v2'|'recaptcha_v3'|'turnstile'| 'hcaptcha', using 'secret_key') or your own CaptchaProviderInterface instance (in which case 'widget' must be a matching CaptchaWidgetDescriptor) — plus 'site_key', 'login', 'register'. login/register may be true/false or an array with 'mode'/'threshold'/'ttl_seconds' (x-failed-attempts, login only), 'min_score' and 'action' (reCAPTCHA v3 / hCaptcha Enterprise only, both optional, built-in providers only).
buildProvider()

CaptchaAddon buildProvider()

source

private static function buildProvider(string $providerKey, string $secretKey, string $siteKey): array

Builds the verifier provider + widget descriptor pair for a provider key.

Param Type Description
$providerKey string 'recaptcha_v2'|'recaptcha_v3'|'turnstile'|'hcaptcha'.
$secretKey string —
$siteKey string —

Returns: array{CaptchaProviderInterface, CaptchaWidgetDescriptor}

Throws When
\InvalidArgumentException When $providerKey isn't recognized.
syncSchema()

CaptchaAddon syncSchema()

source

private static function syncSchema(ContainerInterface $container, array $appConfig): void

Creates/updates the captcha_failed_attempts table via ModuleSchemaBuilder, the same mechanism and config['schema_defaults'] convention core modules use.

Param Type Description
$container ContainerInterface —
$appConfig array<string, mixed> —
attemptKey()

CaptchaAddon attemptKey()

source

private static function attemptKey(?RealIpResolverAdapter $ipAdapter): string

Resolves the throttling key for the current request: the same IP Captcha itself would resolve to (real IP when available, otherwise the naive $_SERVER['REMOTE_ADDR']), falling back to the PHP session id only when no IP information exists at all (e.g. a non-HTTP CLI context).

Param Type Description
$ipAdapter RealIpResolverAdapter|null —

Returns: string

wireLogin()

CaptchaAddon wireLogin()

source

private static function wireLogin(ContainerInterface $container, CaptchaService $service, CaptchaWidgetDescriptor $widget, ?RealIpResolverAdapter $ipAdapter, array $loginConfig): void

Wire CAPTCHA into the login form. In x_failed mode, the widget is shown/verified only after $threshold consecutive failed attempts within $ttlSeconds. An invisible widget (reCAPTCHA v3) has no checkbox to conditionally show, so it always runs.

Param Type Description
$container ContainerInterface —
$service CaptchaService —
$widget CaptchaWidgetDescriptor —
$ipAdapter RealIpResolverAdapter|null —
$loginConfig array<string, mixed> 'mode', 'threshold', 'ttl_seconds', 'min_score', 'action'.
wireRegister()

CaptchaAddon wireRegister()

source

private static function wireRegister(ContainerInterface $container, CaptchaService $service, array $registerConfig): void

Wire CAPTCHA into the register form. Always shown — there is no x-failed-attempts mode for registration.

Param Type Description
$container ContainerInterface —
$service CaptchaService —
$registerConfig array<string, mixed> 'min_score', 'action'.

CaptchaService

final class — rafalmasiarek\DashboardKitCaptcha\CaptchaService · source

Reusable CAPTCHA surface for any module — not just login/register. CaptchaAddon::register() builds one instance from the app's single ['captcha'] config and binds it in the container; any module injects it to render a widget and verify a token, without re-deriving provider/ widget/siteKey wiring itself.

Depends on: CaptchaProviderInterface, CaptchaWidgetDescriptor, HttpClientInterface, RemoteIpProviderInterface

Method Visibility Returns Summary
__construct() public — —
captchaFor() public Captcha A Captcha configured for one usage context. $container labels this instance in log output (e.g. "contactform", "newsletter") — mirrors how wireLogin()/wireRegister() already label theirs "login"/"register".
widget() public string —
scripts() public string —
widgetDescriptor() public CaptchaWidgetDescriptor —
siteKey() public string —
tokenFieldName() public string The form field name the token arrives under — read this instead of hardcoding 'g-recaptcha-response'/'cf-turnstile-response'/etc.
__construct()

CaptchaService __construct()

source

public function __construct(CaptchaProviderInterface $provider, CaptchaWidgetDescriptor $widgetDescriptor, string $siteKey, HttpClientInterface $http, ?RemoteIpProviderInterface $ipProvider)
Param Type Description
$provider CaptchaProviderInterface —
$widgetDescriptor CaptchaWidgetDescriptor —
$siteKey string —
$http HttpClientInterface —
$ipProvider RemoteIpProviderInterface|null —
captchaFor()

CaptchaService captchaFor()

source

public function captchaFor(string $container, ?string $expectedAction, ?float $minScore): Captcha

A Captcha configured for one usage context. $container labels this instance in log output (e.g. "contactform", "newsletter") — mirrors how wireLogin()/wireRegister() already label theirs "login"/"register".

Param Type Description
$container string —
$expectedAction string|null —
$minScore float|null —

Returns: Captcha

widget()

CaptchaService widget()

source

public function widget(string $instanceId, ?string $successCallback, ?string $expiredCallback, string $validationMessage): string
Param Type Description
$instanceId string Give each widget on a page a distinct value.
$successCallback string|null —
$expiredCallback string|null —
$validationMessage string —

Returns: string

scripts()

CaptchaService scripts()

source

public function scripts(string $action, string $instanceId, ?string $successCallback, ?string $expiredCallback, ?string $nonce): string
Param Type Description
$action string —
$instanceId string Must match widget()'s $instanceId for this same widget.
$successCallback string|null —
$expiredCallback string|null —
$nonce string|null CSP nonce, when needed.

Returns: string

widgetDescriptor()

CaptchaService widgetDescriptor()

source

public function widgetDescriptor(): CaptchaWidgetDescriptor

Returns: CaptchaWidgetDescriptor

siteKey()

CaptchaService siteKey()

source

public function siteKey(): string

Returns: string

tokenFieldName()

CaptchaService tokenFieldName()

source

public function tokenFieldName(): string

The form field name the token arrives under — read this instead of hardcoding 'g-recaptcha-response'/'cf-turnstile-response'/etc.

Returns: string

FailedAttemptStoreInterface

interface — rafalmasiarek\DashboardKitCaptcha\FailedAttemptStoreInterface · source

Tracks failed attempts (e.g. logins) under an arbitrary key, with TTL-based expiry. Used by CaptchaAddon to decide whether the x-failed-attempts threshold has been reached — deliberately not keyed by PHP session alone, since an attacker who never retains a session cookie trivially resets a session-only counter on every attempt. The default implementation (FailedAttemptTracker) keys by the caller's real IP instead, falling back to the session only when no IP is available.

Method Visibility Returns Summary
increment() public int Increments the counter for $key and returns the updated value. A counter that has not been touched for $ttlSeconds is treated as expired and restarts from 1 rather than continuing to accumulate.
count() public int —
reset() public void —
increment()

FailedAttemptStoreInterface increment()

source

public function increment(string $key, int $ttlSeconds): int

Increments the counter for $key and returns the updated value. A counter that has not been touched for $ttlSeconds is treated as expired and restarts from 1 rather than continuing to accumulate.

Param Type Description
$key string —
$ttlSeconds int —

Returns: int

count()

FailedAttemptStoreInterface count()

source

public function count(string $key): int
Param Type Description
$key string —

Returns: int — Current count, 0 when absent or expired.

reset()

FailedAttemptStoreInterface reset()

source

public function reset(string $key): void
Param Type Description
$key string —

FailedAttemptTracker

final class — rafalmasiarek\DashboardKitCaptcha\FailedAttemptTracker · source

Database-backed FailedAttemptStoreInterface, via dashboard-kit's Model query builder (Model::on()) — works across whatever PDO driver the app already configured (MySQL/SQLite/Postgres), no addon-specific connection setup needed; CaptchaAddon::syncSchema() creates the table. Two queries (SELECT then INSERT/UPDATE), not one atomic statement — expressing "increment, or reset to 1 if expired" atomically would need per-engine raw SQL (MySQL IF()/SQLite CASE WHEN) that Model::upsert()'s generic VALUES()/excluded. column mapping can't express. The resulting race window (two concurrent attempts from the exact same key reading the same stale count) under-counts by at most one — acceptable for login-attempt throttling, not a correctness-critical counter.

implements FailedAttemptStoreInterface

Method Visibility Returns Summary
increment() public int Increments the counter for $key and returns the updated value. A counter that has not been touched for $ttlSeconds is treated as expired and restarts from 1 rather than continuing to accumulate.
count() public int —
reset() public void —
isExpired() private static bool —
increment()

FailedAttemptTracker increment()

source

public function increment(string $key, int $ttlSeconds): int

Increments the counter for $key and returns the updated value. A counter that has not been touched for $ttlSeconds is treated as expired and restarts from 1 rather than continuing to accumulate.

Param Type Description
$key string —
$ttlSeconds int —

Returns: int

count()

FailedAttemptTracker count()

source

public function count(string $key): int
Param Type Description
$key string —

Returns: int — Current count, 0 when absent or expired.

reset()

FailedAttemptTracker reset()

source

public function reset(string $key): void
Param Type Description
$key string —
isExpired()

FailedAttemptTracker isExpired()

source

private static function isExpired(array $row, \DateTimeImmutable $now): bool
Param Type Description
$row array<string, mixed> —
$now \DateTimeImmutable —

Returns: bool

RealIpResolverAdapter

final class — rafalmasiarek\DashboardKitCaptcha\RealIpResolverAdapter · source

Bridges rafalmasiarek/real-ip-resolver's RealIpResolver (getIp(): string, never null) to rafalmasiarek/captcha's RemoteIpProviderInterface (getRemoteIp(): ?string) — the two can't satisfy each other directly since RealIpResolver doesn't declare the interface itself (and shouldn't: it's a generic library with no reason to know about CAPTCHA concepts). Used both as Captcha's $defaultIpProvider and as the key source for FailedAttemptTracker's per-IP throttling, so both see the exact same resolved IP.

implements RemoteIpProviderInterface

Depends on: RealIpResolver

Method Visibility Returns Summary
__construct() public — —
getRemoteIp() public ?string {@inheritDoc}
__construct()

RealIpResolverAdapter __construct()

source

public function __construct(RealIpResolver $resolver)
Param Type Description
$resolver RealIpResolver —
getRemoteIp()

RealIpResolverAdapter getRemoteIp()

source

public function getRemoteIp(): ?string

{@inheritDoc}

Returns: ?string