rafalmasiarek / dashboard-kit-addon-captcha
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
Requires
- php: >=8.2
- rafalmasiarek/captcha: ^2.0
- rafalmasiarek/dashboard-kit: >=5.4.2
- rafalmasiarek/real-ip-resolver: ^2.3
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-17 23:37:15 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
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
CaptchaAddon—rafalmasiarek\DashboardKitCaptchaCaptchaService—rafalmasiarek\DashboardKitCaptchaFailedAttemptTracker—rafalmasiarek\DashboardKitCaptchaRealIpResolverAdapter—rafalmasiarek\DashboardKitCaptcha
Interfaces
FailedAttemptStoreInterface—rafalmasiarek\DashboardKitCaptcha
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
public function widgetDescriptor(): CaptchaWidgetDescriptor
Returns: CaptchaWidgetDescriptor
tokenFieldName()
CaptchaService tokenFieldName()
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()
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()
public function count(string $key): int
| Param | Type | Description |
|---|---|---|
$key |
string |
— |
Returns: int — Current count, 0 when absent or expired.
reset()
FailedAttemptStoreInterface reset()
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()
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()
public function count(string $key): int
| Param | Type | Description |
|---|---|---|
$key |
string |
— |
Returns: int — Current count, 0 when absent or expired.
reset()
FailedAttemptTracker reset()
public function reset(string $key): void
| Param | Type | Description |
|---|---|---|
$key |
string |
— |
isExpired()
FailedAttemptTracker isExpired()
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()
public function __construct(RealIpResolver $resolver)
| Param | Type | Description |
|---|---|---|
$resolver |
RealIpResolver |
— |