CreaCaptcha

Documentation

Table of Contents

Packages

Application
Creationell

Namespaces

Creationell

Constants

CREATIONELL_CAPTCHA_BASENAME  = \plugin_basename(__FILE__)
CREATIONELL_CAPTCHA_DEBUG  = \defined('WP_DEBUG') && \WP_DEBUG
CREATIONELL_CAPTCHA_EXPORT_SCHEMA  = 1
Schema version of the settings-export format.
CREATIONELL_CAPTCHA_FILE  = __FILE__
CREATIONELL_CAPTCHA_LOCALE_MAP  = [ // Deutsch 'de_DE' => 'de', 'de_DE_formal' => 'de', 'de_AT' => 'de', 'de_CH' => 'de', 'de_CH_informal' => 'de', // Englisch 'en_US' => 'en', 'en_GB' => 'en', 'en_AU' => 'en', 'en_CA' => 'en', 'en_NZ' => 'en', 'en_ZA' => 'en', // Französisch 'fr_FR' => 'fr-fr', 'fr_BE' => 'fr-fr', 'fr_LU' => 'fr-fr', 'fr_CH' => 'fr-fr', 'fr_CA' => 'fr-ca', // Spanisch (Europa) 'es_ES' => 'es-es', // Spanisch (LatAm — alle nach es-419) 'es_AR' => 'es-419', 'es_CL' => 'es-419', 'es_CO' => 'es-419', 'es_CR' => 'es-419', 'es_DO' => 'es-419', 'es_EC' => 'es-419', 'es_GT' => 'es-419', 'es_HN' => 'es-419', 'es_MX' => 'es-419', 'es_PA' => 'es-419', 'es_PE' => 'es-419', 'es_PR' => 'es-419', 'es_UY' => 'es-419', 'es_VE' => 'es-419', // Portugiesisch 'pt_PT' => 'pt-pt', 'pt_AO' => 'pt-pt', 'pt_BR' => 'pt-br', // Italienisch / Niederländisch / Polnisch 'it_IT' => 'it', 'nl_NL' => 'nl', 'nl_BE' => 'nl', 'pl_PL' => 'pl', // Tschechisch / Slowakisch 'cs_CZ' => 'cs', 'sk_SK' => 'sk', // Nordisch 'da_DK' => 'da', 'sv_SE' => 'sv', 'fi' => 'fi', 'nb_NO' => 'nb', 'nn_NO' => 'nb', // Sonstige EU 'hu_HU' => 'hu', 'ro_RO' => 'ro', 'el' => 'el', ]
Maps WordPress locales to the matching ALTCHA i18n locale bundle.
CREATIONELL_CAPTCHA_MIN_PHP  = '8.3'
CREATIONELL_CAPTCHA_MIN_WP  = '6.9'
CREATIONELL_CAPTCHA_PLUGIN_PATH  = \plugin_dir_path(__FILE__)
CREATIONELL_CAPTCHA_PLUGIN_URL  = \plugin_dir_url(__FILE__)
CREATIONELL_CAPTCHA_VERSION  = '1.0.1'

Functions

creationell_captcha_register_admin_menu()  : void
Registers the top-level "CreaCaptcha" admin menu entry.
creationell_captcha_render_settings_page()  : void
Renders the tabbed settings page.
creationell_captcha_render_trust_notice()  : void
Renders the "proxy mode on but trust-set empty" admin notice on plugin pages.
creationell_captcha_tabbed_page_hooks()  : array<int, string>
Records and reports the admin-page hook suffixes of the plugin's tab-organised pages.
creationell_captcha_active_tab()  : string
Determines the active tab from the request, whitelisted against $tabs.
creationell_captcha_render_nav_tabs()  : void
Renders the no-JavaScript fallback style and the nav-tab bar.
creationell_captcha_csv_cell()  : string
Neutralises a CSV cell against spreadsheet formula injection.
creationell_captcha_export_events()  : void
Streams the filtered event log as a CSV download.
creationell_captcha_register_analytics_page()  : void
Registers the "Statistik" submenu page under the CreaCaptcha menu.
creationell_captcha_analytics_labels()  : array<string, string>
Human-readable labels for the seven event types.
creationell_captcha_analytics_groups()  : array<int, array{title: string, description: string, types: array}>
Thematic groups for the overview tab: title, explanation and the member event types with their short in-group labels.
creationell_captcha_analytics_tabs()  : array<string, string>
The three tabs of the analytics page.
creationell_captcha_sum_recent_days()  : array<string, int>
Sums the $days most recent day buckets, per event type.
creationell_captcha_sum_recent_hours()  : array<string, int>
Sums the $hours most recent hour buckets, per event type.
creationell_captcha_render_analytics_page()  : void
Renders the tabbed analytics dashboard page.
creationell_captcha_render_analytics_overview()  : void
Renders the "Übersicht" tab: four 24-hour KPI tiles and one four-window comparison table per thematic group.
creationell_captcha_render_analytics_history()  : void
Renders the "Verlauf" tab: the day-by-day table for the last 30 days.
creationell_captcha_events_query_args()  : array{search: string, event_type: string, date_from: string, date_to: string}
Reads and sanitises the event-log filter from the request.
creationell_captcha_render_analytics_events()  : void
Renders the "Ereignisse" tab: filter toolbar, the event table with a detail link per row, the embedded event data and the detail modal.
creationell_captcha_render_event_modal()  : void
Renders the (initially hidden) event-detail modal skeleton.
creationell_captcha_render_events_toolbar()  : void
Renders the event-log filter toolbar: search, type filter, date range, the "Filtern"/"Zurücksetzen" controls and the CSV export link.
creationell_captcha_render_events_pagination()  : void
Renders the pagination navigation below the event-log table.
creationell_captcha_analytics()  : Analytics
Returns the shared analytics recorder instance.
creationell_captcha_record_event()  : void
Records a security event of the given type.
creationell_captcha_enqueue_admin_assets()  : void
Enqueues admin styles and scripts on the CreaCaptcha admin pages.
creationell_captcha_cloudflare_snapshot()  : array{v4: string[], v6: string[], updated_at: string}
Returns the bundled Cloudflare snapshot.
creationell_captcha_cloudflare_ranges()  : array<string|int, string>
The active CF range list: cached option (if fresh) → bundled snapshot.
creationell_captcha_refresh_cloudflare_ips_now()  : array{ok: bool, v4: int, v6: int, fetched_at: int|null, error: string|null}
Fetches the live Cloudflare ranges and writes them to the cache option.
creationell_captcha_clear_cloudflare_cache()  : bool
Deletes the cached Cloudflare-range option. The next read falls back to the bundled snapshot. Returns true when the option existed and was deleted, false when the option was absent or the delete failed.
creationell_captcha_fetch_cloudflare_list()  : array<string|int, string>
Fetches one Cloudflare endpoint and returns the valid CIDR entries.
creationell_captcha_sync_cloudflare_cron()  : void
Ensures the daily refresh cron slot is in sync with the auto-refresh toggle.
creationell_captcha_render_code_image()  : string
Renders a PNG of the given code and returns the raw bytes. Caller is responsible for emitting headers (`Content-Type: image/png`, `Cache-Control: no-store`) and the body.
creationell_captcha_should_issue_code_challenge()  : bool
Decides whether the current /challenge request should attach a code-challenge instruction. Returns true iff:
creationell_captcha_code_charset()  : string
Returns the active charset string for the configured option.
creationell_captcha_generate_code()  : string
Generates a fresh random code from the configured charset.
creationell_captcha_code_token_issue()  : string
Issues a token backed by a server-side WP transient that stores the expected code for at most $expiry_seconds. Returns the opaque ID that `/code-image` and `/code-verify` use to look the code up again.
creationell_captcha_code_token_verify()  : string|null
Looks up the code for a token and returns it, or null on: - malformed token (not 32 hex chars) - missing transient (expired or unknown)
creationell_captcha_rest_code_image()  : WP_REST_Response
Handles GET /code-image?t=<token>. Looks up the code from the token (server-side transient), renders the PNG, returns 410 on token failure.
creationell_captcha_rest_code_verify()  : WP_REST_Response
Handles POST /code-verify. Two body shapes:
creationell_captcha_register_code_challenge_routes()  : void
Registers the two code-challenge REST routes. The /challenge handler itself stays in includes/rest.php; Task 11 extends it with the codeChallenge field and the data.ccode embed.
creationell_captcha_register_email_obfuscation()  : void
Registers email obfuscation on `init`. The decoder script is always registered; then, unless the kill-switch is set or the feature is off, the configured mode is wired up — the content filters (module 7) or the full-page output buffer (module 8).
creationell_captcha_register_email_buffer()  : void
Wires up the full-page-buffer mode: on `template_redirect` for non-feed front-end requests it enqueues the decoder script and starts an output buffer whose callback obfuscates the page body at flush time.
creationell_captcha_run_firewall()  : void
Runs the IP/user-agent firewall. Hooked on `init` at priority 0 so it fires before the rate limiter, the interceptor and any form-processing handler.
creationell_captcha_comments_active()  : bool
Whether comment protection applies to the current request.
creationell_captcha_comments_render()  : string
Injects the widget just above the comment form submit button.
creationell_captcha_comments_verify()  : array<string, mixed>
Verifies the captcha before a comment is accepted.
creationell_captcha_login_enabled()  : bool
Whether login protection is enabled.
creationell_captcha_login_render()  : void
Renders the widget inside the login form.
creationell_captcha_login_verify()  : WP_User|WP_Error|null
Verifies the captcha during an interactive login.
creationell_captcha_password_reset_enabled()  : bool
Whether password-reset protection is enabled.
creationell_captcha_password_reset_render()  : void
Renders the widget inside the lost-password form.
creationell_captcha_password_reset_verify()  : void
Verifies the captcha during a password-reset request.
creationell_captcha_registration_enabled()  : bool
Whether registration protection is enabled.
creationell_captcha_registration_render()  : void
Renders the widget inside the registration form.
creationell_captcha_registration_verify()  : WP_Error
Verifies the captcha during registration.
creationell_captcha_resolve_widget_locale()  : string|null
Resolves the active WordPress locale to a vendored ALTCHA locale code.
creationell_captcha_get_default_settings()  : array<string, mixed>
Default plugin settings.
creationell_captcha_get_settings()  : array<string, mixed>
Current plugin settings, merged over the defaults.
creationell_captcha_invalidate_settings_cache()  : void
Drops the in-request settings cache. Wired to the option-change hooks below so callers that read settings after an update see the fresh value.
creationell_captcha_is_disabled()  : bool
Whether the captcha is globally disabled via the wp-config constant.
creationell_captcha_sodium_available()  : bool
Whether ext-sodium (required for Argon2id) is available.
creationell_captcha_generate_secrets()  : array{signature: string, key_signature: string}
Generates both HMAC secrets and persists them (non-autoloaded).
creationell_captcha_get_secret()  : string
Returns a stored HMAC secret, generating + persisting it on first use.
creationell_captcha_get_hmac_secret()  : string
The HMAC signature secret (signs each challenge).
creationell_captcha_get_hmac_key_secret()  : string
The HMAC key-signature secret (enables the fast verification path).
creationell_captcha_engine()  : Engine
Shared captcha engine instance.
creationell_captcha_log()  : void
Write a message to the debug log when CREATIONELL_CAPTCHA_DEBUG is active.
creationell_captcha_get_client_ip()  : string
Resolves the client IP address.
creationell_captcha_ip_in_list()  : bool
Whether an IP matches any entry in a list of IPs or CIDR ranges.
creationell_captcha_ip_in_cidr()  : bool
Whether an IP falls within a CIDR range. Supports IPv4 and IPv6.
creationell_captcha_is_valid_ip_or_cidr()  : bool
Whether a string is a valid IP address or CIDR range (IPv4 or IPv6).
creationell_captcha_wildcard_match()  : bool
Whether a subject matches any of the given wildcard patterns (case-insensitive).
creationell_captcha_private_ranges()  : array<string|int, string>
Returns the canonical list of private/loopback CIDR ranges used when the `firewall_trust_private_ranges` toggle is active.
creationell_captcha_trusted_proxies_constant()  : array<string|int, string>
Reads the optional `CREATIONELL_CAPTCHA_TRUSTED_PROXIES` wp-config constant as a list. Accepts either a string array or a comma/whitespace-separated scalar; invalid entries are dropped.
creationell_captcha_is_trusted_proxy()  : bool
Whether the given IP belongs to a trusted upstream proxy.
creationell_captcha_evaluate_bypass()  : array{reason: string, source: string}|false
Pure bypass evaluator — checks the three bypass sources against the supplied inputs without touching $_SERVER, $_COOKIE or any static cache. The caller is responsible for providing the values.
creationell_captcha_request_bypassed()  : array{reason: string, source: string}|false
Whether the current request is allowed to bypass captcha, under-attack and firewall protections. Reads $_SERVER, $_COOKIE and the request's client IP, then delegates to `creationell_captcha_evaluate_bypass()`.
creationell_captcha_validate_action_pattern()  : string|null
Validates a single interceptor-action pattern.
creationell_captcha_validate_cookie_entry()  : string|null
Validates a single bypass-cookie entry of the form `name=value`.
creationell_captcha_anonymize_ip()  : string
Truncates an IP for DSGVO-compliant storage. IPv4 → last octet zeroed, IPv6 → last 80 bits zeroed. Invalid IPs return ''.
creationell_captcha_request_body_fingerprint()  : string
Returns a JSON-encoded fingerprint of $_POST: { field-name: value-byte-length }.
creationell_captcha_block_response()  : void
Sends a fail-closed block response and terminates the request.
creationell_captcha_base64url_encode()  : string
Base64URL encoder (RFC 4648 §5) — strips standard-base64 padding and replaces +/ with -_ so the value is URL-safe.
creationell_captcha_base64url_decode()  : string
Base64URL decoder — accepts unpadded URL-safe input and returns the raw bytes. Returns the empty string on malformed input (no exceptions).
creationell_captcha_ratelimit_current_count()  : int
Reads the current rate-limit counter for an IP without incrementing it.
creationell_captcha_cf7_active()  : bool
Whether the Contact Form 7 integration is active.
creationell_captcha_cf7_register_tag()  : void
Registers the [creationell_captcha] Contact Form 7 form-tag.
creationell_captcha_cf7_tag_handler()  : string
Renders the widget for the [creationell_captcha] form-tag.
creationell_captcha_cf7_auto_inject()  : string
Auto-injects the widget into CF7 forms without a [creationell_captcha] tag.
creationell_captcha_cf7_verify()  : bool
Verifies the captcha on a Contact Form 7 submission.
creationell_captcha_forminator_active()  : bool
Whether the Forminator integration is active.
creationell_captcha_forminator_inject()  : string
Auto-injects the widget before the submit button of a Forminator custom form.
creationell_captcha_forminator_verify()  : array<int, array<string, string>>
Verifies the captcha on a Forminator custom-form submission.
creationell_captcha_woocommerce_active()  : bool
Whether any WooCommerce protection applies right now.
creationell_captcha_wc_checkout_active()  : bool
Whether the WooCommerce checkout protection is active.
creationell_captcha_wc_checkout_render()  : void
Renders the widget directly before the Place-Order button on the checkout.
creationell_captcha_wc_checkout_verify()  : void
Verifies the captcha during checkout validation.
creationell_captcha_wc_login_active()  : bool
Whether the WooCommerce my-account login protection is active.
creationell_captcha_wc_login_render()  : void
Renders the widget at the bottom of the WooCommerce login form.
creationell_captcha_wc_login_verify()  : mixed
Verifies the captcha on a WooCommerce my-account login submission.
creationell_captcha_wc_registration_active()  : bool
Whether the WooCommerce registration protection is active.
creationell_captcha_wc_registration_render()  : void
Renders the widget at the bottom of the WooCommerce registration form.
creationell_captcha_wc_registration_verify()  : mixed
Verifies the captcha during WooCommerce my-account registration.
creationell_captcha_wc_lost_password_active()  : bool
Whether the WooCommerce lost-password render is active.
creationell_captcha_wc_lost_password_render()  : void
Renders the widget inside the WooCommerce lost-password form.
creationell_captcha_wpforms_active()  : bool
Whether the WPForms integration is active.
creationell_captcha_wpforms_inject()  : void
Auto-injects the widget directly before the WPForms submit button.
creationell_captcha_wpforms_verify()  : void
Verifies the captcha on a WPForms submission.
creationell_captcha_interceptor_inject_buffer_start()  : void
Conditionally starts the output buffer on template_redirect priority 0.
creationell_captcha_interceptor_inject_buffer()  : string
Buffer callback. Replaces every `<form …>…</form>` with the same form plus an `<altcha-widget>` inserted directly before `</form>`. Idempotent — forms that already contain `<altcha-widget` are returned unchanged.
creationell_captcha_run_interceptor()  : void
Runs the request interceptor. Hooked on `init` at priority 1 so it fires before any form-processing handler.
creationell_captcha_protect_path()  : void
Registers one or more path patterns to be guarded by the interceptor.
creationell_captcha_activate()  : void
Runs on plugin activation: seeds default options and HMAC secrets.
creationell_captcha_deactivate()  : void
Runs on plugin deactivation: clears scheduled cron slots and lets every module react via the `creationell_captcha_deactivated` action hook.
creationell_captcha_run_rate_limiter()  : void
Runs the per-IP rate limiter. Hooked on `init` at priority 0; registered after the firewall so the firewall runs first.
creationell_captcha_register_rest_routes()  : void
Registers the public challenge route.
creationell_captcha_rest_challenge()  : WP_REST_Response
Returns a fresh, single-use challenge. Records the issuance via the standard event channel — aggregate counters always increment, the detail-log entry is gated by the `log_challenge` per-type toggle from Modul 11c.
creationell_captcha_canonical_params_json()  : string
Canonical-JSON serialisation of ALTCHA challenge parameters, byte- identical to `altcha-lib-php`'s `ChallengeParameters::toCanonicalJson()` (= ksort top-level + recursive ksort on assoc sub-arrays, JSON-encoded with UNESCAPED_SLASHES | UNESCAPED_UNICODE, null keys dropped).
creationell_captcha_canonical_sort_recursive()  : void
Recursive helper used by `canonical_params_json` — mirrors the lib's `sortRecursive`. List arrays (sequential integer keys) keep their order; associative arrays get `ksort`-ed in place.
creationell_captcha_list_setting_keys()  : array<int, string>
Setting keys whose value is a list (every `textarea` field).
creationell_captcha_export_settings()  : array<string, mixed>
Builds the settings-export payload.
creationell_captcha_import_settings()  : array<string, mixed>|WP_Error
Validates and applies a settings-export payload.
creationell_captcha_reset_settings()  : void
Full factory reset: writes the complete default settings array, which also empties every list. Secrets, analytics counters and the event log are left untouched.
creationell_captcha_load_default_settings()  : void
Resets every non-list setting to its default while preserving the current list values (IP block/allow, UA block, interceptor paths).
creationell_captcha_admin_tabs()  : array<string, string>
Ordered list of the admin settings tabs.
creationell_captcha_admin_sections()  : array<string, array<string, string>>
Settings sections and the tab each one belongs to.
creationell_captcha_settings_fields()  : array<string, array<string, mixed>>
Field specification for the captcha settings.
creationell_captcha_register_settings()  : void
Registers the plugin setting, the per-tab sections and the fields.
creationell_captcha_sanitize_settings()  : array<string, mixed>
Sanitises the settings array before it is stored.
creationell_captcha_render_engine_section()  : void
Renders the description shown at the top of the Proof-of-Work-Engine section.
creationell_captcha_render_widget_appearance_section()  : void
Renders the description shown at the top of the widget-appearance section.
creationell_captcha_render_code_challenge_section()  : void
Renders the description shown at the top of the code-challenge section.
creationell_captcha_render_core_forms_section()  : void
Renders the description shown at the top of the core-forms section.
creationell_captcha_render_interceptor_section()  : void
Renders the description shown at the top of the interceptor section.
creationell_captcha_render_form_plugins_section()  : void
Renders the description shown at the top of the form-plugins section.
creationell_captcha_render_proxy_section()  : void
Renders the description shown at the top of the proxy section.
creationell_captcha_render_bypass_section()  : void
Renders the description shown at the top of the bypass section.
creationell_captcha_render_firewall_section()  : void
Renders the description shown at the top of the firewall section.
creationell_captcha_render_ratelimit_section()  : void
Renders the description shown at the top of the rate-limiting section.
creationell_captcha_render_underattack_section()  : void
Renders the description shown at the top of the under-attack section.
creationell_captcha_render_underattack_appearance_section()  : void
Renders the description shown at the top of the under-attack appearance section.
creationell_captcha_render_analytics_section()  : void
Renders the description shown at the top of the analytics section.
creationell_captcha_render_email_section()  : void
Renders the description shown at the top of the email-protection section.
creationell_captcha_render_field()  : void
Renders a single settings field.
creationell_captcha_tools_redirect()  : never
Stores a one-shot admin notice and redirects back to the Werkzeuge page.
creationell_captcha_tools_guard()  : void
Guards a tools action: requires manage_options and a valid nonce.
creationell_captcha_handle_export_settings()  : void
Streams the current settings as a JSON download.
creationell_captcha_handle_import_settings()  : void
Handles the settings-import upload.
creationell_captcha_handle_reset_settings()  : void
Handles the full factory reset.
creationell_captcha_handle_load_defaults()  : void
Handles "load defaults" (keeps the lists).
creationell_captcha_handle_cloudflare_refresh()  : void
Triggers a manual Cloudflare-range refresh from the Werkzeuge page.
creationell_captcha_handle_cloudflare_clear()  : void
Empties the cached Cloudflare-range option from the Werkzeuge page.
creationell_captcha_register_tools_page()  : void
Registers the "Werkzeuge" submenu page under the CreaCaptcha menu.
creationell_captcha_render_tools_notice()  : void
Renders the one-shot admin notice left behind by a tools action.
creationell_captcha_render_tools_page()  : void
Renders the "Werkzeuge" page.
creationell_captcha_render_cloudflare_status()  : void
Renders the Cloudflare-cache status block inside the Werkzeuge tool card.
creationell_captcha_run_under_attack()  : void
Runs the under-attack interstitial gate for front-end page views. Hooked on `template_redirect` — fires only for front-end requests, so wp-admin, wp-login.php, REST and cron are inherently exempt.
creationell_captcha_maybe_upgrade()  : void
Runs schema migrations when the stored version differs from the running one.
creationell_captcha_migrate_widget_mode()  : void
Migrates the legacy `widget_mode` setting (Modul 11a) to the new `widget_display` + `widget_auto_trigger` pair (Modul 14). Idempotent — if `widget_display` is already present in the stored option, the migration is skipped.
creationell_captcha_register_assets()  : void
Registers the widget script and — for Argon2id — its worker registration.
creationell_captcha_build_widget_markup()  : string
Builds the ALTCHA widget markup as a plain string. Enqueues the widget script as a side effect.
creationell_captcha_render_widget()  : void
Renders the ALTCHA widget markup and enqueues its assets.
creationell_captcha_verify_payload()  : bool
Verifies a raw base64 ALTCHA payload string.
creationell_captcha_verify_request()  : bool
Reads and verifies the ALTCHA payload from the current POST request.
creationell_captcha_widget()  : void
Public template tag — renders the ALTCHA widget.
creationell_captcha_get_widget_markup()  : string
Returns the ALTCHA widget markup as a string.
creationell_captcha_widget_shortcode()  : string
Shortcode handler for [creationell_captcha].

Constants

CREATIONELL_CAPTCHA_BASENAME

public mixed CREATIONELL_CAPTCHA_BASENAME = \plugin_basename(__FILE__)

CREATIONELL_CAPTCHA_DEBUG

public mixed CREATIONELL_CAPTCHA_DEBUG = \defined('WP_DEBUG') && \WP_DEBUG

CREATIONELL_CAPTCHA_EXPORT_SCHEMA

Schema version of the settings-export format.

public mixed CREATIONELL_CAPTCHA_EXPORT_SCHEMA = 1

CREATIONELL_CAPTCHA_LOCALE_MAP

Maps WordPress locales to the matching ALTCHA i18n locale bundle.

public mixed CREATIONELL_CAPTCHA_LOCALE_MAP = [ // Deutsch 'de_DE' => 'de', 'de_DE_formal' => 'de', 'de_AT' => 'de', 'de_CH' => 'de', 'de_CH_informal' => 'de', // Englisch 'en_US' => 'en', 'en_GB' => 'en', 'en_AU' => 'en', 'en_CA' => 'en', 'en_NZ' => 'en', 'en_ZA' => 'en', // Französisch 'fr_FR' => 'fr-fr', 'fr_BE' => 'fr-fr', 'fr_LU' => 'fr-fr', 'fr_CH' => 'fr-fr', 'fr_CA' => 'fr-ca', // Spanisch (Europa) 'es_ES' => 'es-es', // Spanisch (LatAm — alle nach es-419) 'es_AR' => 'es-419', 'es_CL' => 'es-419', 'es_CO' => 'es-419', 'es_CR' => 'es-419', 'es_DO' => 'es-419', 'es_EC' => 'es-419', 'es_GT' => 'es-419', 'es_HN' => 'es-419', 'es_MX' => 'es-419', 'es_PA' => 'es-419', 'es_PE' => 'es-419', 'es_PR' => 'es-419', 'es_UY' => 'es-419', 'es_VE' => 'es-419', // Portugiesisch 'pt_PT' => 'pt-pt', 'pt_AO' => 'pt-pt', 'pt_BR' => 'pt-br', // Italienisch / Niederländisch / Polnisch 'it_IT' => 'it', 'nl_NL' => 'nl', 'nl_BE' => 'nl', 'pl_PL' => 'pl', // Tschechisch / Slowakisch 'cs_CZ' => 'cs', 'sk_SK' => 'sk', // Nordisch 'da_DK' => 'da', 'sv_SE' => 'sv', 'fi' => 'fi', 'nb_NO' => 'nb', 'nn_NO' => 'nb', // Sonstige EU 'hu_HU' => 'hu', 'ro_RO' => 'ro', 'el' => 'el', ]

Keys are values returned by get_locale() — including the formal / informal variants WP exposes (de_DE_formal, de_CH_informal). Values are the exact locale codes used by the vendored ALTCHA bundles under assets/js/altcha-i18n/<code>.js. Locales not in the map fall through to the widget's own auto-detection (which itself falls back to English since only the bundles enqueued by this plugin are registered).

Extend via the creationell_captcha_widget_locale_map filter rather than patching this constant.

CREATIONELL_CAPTCHA_PLUGIN_PATH

public mixed CREATIONELL_CAPTCHA_PLUGIN_PATH = \plugin_dir_path(__FILE__)

CREATIONELL_CAPTCHA_PLUGIN_URL

public mixed CREATIONELL_CAPTCHA_PLUGIN_URL = \plugin_dir_url(__FILE__)

Functions

creationell_captcha_register_admin_menu()

Registers the top-level "CreaCaptcha" admin menu entry.

creationell_captcha_register_admin_menu() : void

creationell_captcha_render_settings_page()

Renders the tabbed settings page.

creationell_captcha_render_settings_page() : void

All tabs share one

and one submit button — the tab panels are only a display split, so saving always persists every field at once. PHP marks one tab active server-side; admin.js switches tabs client-side; the

creationell_captcha_render_trust_notice()

Renders the "proxy mode on but trust-set empty" admin notice on plugin pages.

creationell_captcha_render_trust_notice() : void

The notice is persistent (not dismissible) — it disappears automatically as soon as any trust source is configured.

creationell_captcha_tabbed_page_hooks()

Records and reports the admin-page hook suffixes of the plugin's tab-organised pages.

creationell_captcha_tabbed_page_hooks([mixed $add = null ]) : array<int, string>

A submenu page's hook suffix derives from the sanitised parent menu title, not its slug, so it cannot be reliably hardcoded. Each tabbed page passes the value WordPress returns from add_menu_page()/add_submenu_page() here, and the admin asset loader matches the current screen against the recorded set.

Parameters
$add : mixed = null

Hook suffix to record; ignored unless a non-empty string.

Return values
array<int, string>

All recorded hook suffixes.

creationell_captcha_active_tab()

Determines the active tab from the request, whitelisted against $tabs.

creationell_captcha_active_tab(array<string, string> $tabs) : string

Falls back to the first tab when no valid tab query parameter is present. The value only selects which panel is shown and is strictly whitelisted against the given registry, so no nonce check is required.

Parameters
$tabs : array<string, string>

Tab registry (id => label).

Return values
string

Active tab id.

creationell_captcha_render_nav_tabs()

Renders the no-JavaScript fallback style and the nav-tab bar.

creationell_captcha_render_nav_tabs(array<string, string> $tabs, string $active_tab, string $base_url) : void

Without JavaScript the per-tab panels would each be hidden by admin.css; the

Parameters
$tabs : array<string, string>

Tab registry (id => label).

$active_tab : string

Active tab id.

$base_url : string

Page URL the tab links point at.

creationell_captcha_csv_cell()

Neutralises a CSV cell against spreadsheet formula injection.

creationell_captcha_csv_cell(string $value) : string

A value beginning with =, +, - or @ can be executed as a formula by Excel or LibreOffice; the path column carries attacker-controlled request URIs. A leading single quote forces the spreadsheet to treat the value as text.

Parameters
$value : string

Raw cell value.

Return values
string

creationell_captcha_export_events()

Streams the filtered event log as a CSV download.

creationell_captcha_export_events() : void

Hooked to admin-post.php. Requires the manage_options capability and a valid nonce. The filter (search, event type, date range) is read from the request via the shared parser, so the export mirrors the on-screen filter.

creationell_captcha_register_analytics_page()

Registers the "Statistik" submenu page under the CreaCaptcha menu.

creationell_captcha_register_analytics_page() : void

creationell_captcha_analytics_labels()

Human-readable labels for the seven event types.

creationell_captcha_analytics_labels() : array<string, string>
Return values
array<string, string>

creationell_captcha_analytics_groups()

Thematic groups for the overview tab: title, explanation and the member event types with their short in-group labels.

creationell_captcha_analytics_groups() : array<int, array{title: string, description: string, types: array}>

Together the groups cover all seven event types exactly once. The long labels from creationell_captcha_analytics_labels() stay untouched for the filter dropdown, CSV export, CLI and history tab.

Return values
array<int, array{title: string, description: string, types: array}>

creationell_captcha_analytics_tabs()

The three tabs of the analytics page.

creationell_captcha_analytics_tabs() : array<string, string>
Return values
array<string, string>

Tab id => visible label.

creationell_captcha_sum_recent_days()

Sums the $days most recent day buckets, per event type.

creationell_captcha_sum_recent_days(array<string, array<string, int>> $daily, int $days) : array<string, int>

Iterates today plus the ($days - 1) preceding days — the same window the 30-day history table walks.

Parameters
$daily : array<string, array<string, int>>

Daily counters keyed by 'Y-m-d'.

$days : int

Number of day buckets to sum.

Return values
array<string, int>

Event type => sum.

creationell_captcha_sum_recent_hours()

Sums the $hours most recent hour buckets, per event type.

creationell_captcha_sum_recent_hours(array<string, array<string, int>> $hourly, int $hours) : array<string, int>

Iterates the current hour plus the ($hours - 1) preceding hours.

Parameters
$hourly : array<string, array<string, int>>

Hourly counters keyed by 'Y-m-d H'.

$hours : int

Number of hour buckets to sum.

Return values
array<string, int>

Event type => sum.

creationell_captcha_render_analytics_page()

Renders the tabbed analytics dashboard page.

creationell_captcha_render_analytics_page() : void

creationell_captcha_render_analytics_overview()

Renders the "Übersicht" tab: four 24-hour KPI tiles and one four-window comparison table per thematic group.

creationell_captcha_render_analytics_overview() : void

creationell_captcha_render_analytics_history()

Renders the "Verlauf" tab: the day-by-day table for the last 30 days.

creationell_captcha_render_analytics_history() : void

creationell_captcha_events_query_args()

Reads and sanitises the event-log filter from the request.

creationell_captcha_events_query_args() : array{search: string, event_type: string, date_from: string, date_to: string}

Used by the "Ereignisse" tab and by the CSV export handler. The values only narrow a read-only query and are bound via $wpdb->prepare downstream, so no nonce check is required here; the page number is read separately by the tab.

Return values
array{search: string, event_type: string, date_from: string, date_to: string}

creationell_captcha_render_analytics_events()

Renders the "Ereignisse" tab: filter toolbar, the event table with a detail link per row, the embedded event data and the detail modal.

creationell_captcha_render_analytics_events() : void

creationell_captcha_render_event_modal()

Renders the (initially hidden) event-detail modal skeleton.

creationell_captcha_render_event_modal() : void

The value cells carry a data-field matching the event record key; the modal JavaScript fills them client-side from the embedded JSON map.

creationell_captcha_render_events_toolbar()

Renders the event-log filter toolbar: search, type filter, date range, the "Filtern"/"Zurücksetzen" controls and the CSV export link.

creationell_captcha_render_events_toolbar(array{search: string, event_type: string, date_from: string, date_to: string} $filter) : void
Parameters
$filter : array{search: string, event_type: string, date_from: string, date_to: string}

Active filter.

creationell_captcha_render_events_pagination()

Renders the pagination navigation below the event-log table.

creationell_captcha_render_events_pagination(array{search: string, event_type: string, date_from: string, date_to: string} $filter, int $paged, int $total_pages) : void
Parameters
$filter : array{search: string, event_type: string, date_from: string, date_to: string}

Active filter.

$paged : int

Current page (1-based).

$total_pages : int

Total page count.

creationell_captcha_analytics()

Returns the shared analytics recorder instance.

creationell_captcha_analytics() : Analytics
Return values
Analytics

creationell_captcha_record_event()

Records a security event of the given type.

creationell_captcha_record_event(string $type[, array<string, mixed> $context = [] ]) : void
Parameters
$type : string

The event type.

$context : array<string, mixed> = []

Optional caller-supplied context.

creationell_captcha_enqueue_admin_assets()

Enqueues admin styles and scripts on the CreaCaptcha admin pages.

creationell_captcha_enqueue_admin_assets(string $hook_suffix) : void
Parameters
$hook_suffix : string

Current admin page hook suffix.

creationell_captcha_cloudflare_snapshot()

Returns the bundled Cloudflare snapshot.

creationell_captcha_cloudflare_snapshot() : array{v4: string[], v6: string[], updated_at: string}
Return values
array{v4: string[], v6: string[], updated_at: string}

creationell_captcha_cloudflare_ranges()

The active CF range list: cached option (if fresh) → bundled snapshot.

creationell_captcha_cloudflare_ranges() : array<string|int, string>

The cached option is considered stale once it is older than 48 hours, shielding against a silently broken cron job.

Return values
array<string|int, string>

IPv4 and IPv6 CIDR ranges, merged.

creationell_captcha_refresh_cloudflare_ips_now()

Fetches the live Cloudflare ranges and writes them to the cache option.

creationell_captcha_refresh_cloudflare_ips_now() : array{ok: bool, v4: int, v6: int, fetched_at: int|null, error: string|null}
Return values
array{ok: bool, v4: int, v6: int, fetched_at: int|null, error: string|null}

creationell_captcha_clear_cloudflare_cache()

Deletes the cached Cloudflare-range option. The next read falls back to the bundled snapshot. Returns true when the option existed and was deleted, false when the option was absent or the delete failed.

creationell_captcha_clear_cloudflare_cache() : bool
Return values
bool

creationell_captcha_fetch_cloudflare_list()

Fetches one Cloudflare endpoint and returns the valid CIDR entries.

creationell_captcha_fetch_cloudflare_list(string $url) : array<string|int, string>
Parameters
$url : string
Return values
array<string|int, string>

creationell_captcha_sync_cloudflare_cron()

Ensures the daily refresh cron slot is in sync with the auto-refresh toggle.

creationell_captcha_sync_cloudflare_cron() : void

Hooked on update_option_creationell_captcha_settings (fires on every settings save). Deactivation cleanup is handled explicitly in creationell_captcha_deactivate() to avoid re-scheduling the slot during the deactivation handler.

creationell_captcha_render_code_image()

Renders a PNG of the given code and returns the raw bytes. Caller is responsible for emitting headers (`Content-Type: image/png`, `Cache-Control: no-store`) and the body.

creationell_captcha_render_code_image(string $code) : string

Falls back to GD's built-in bitmap font 5 if the vendored TTF is missing (logs a one-line warning so the operator sees the degradation).

Parameters
$code : string

The code to render (4–8 chars expected; longer is trimmed implicitly by the width budget).

Return values
string

creationell_captcha_should_issue_code_challenge()

Decides whether the current /challenge request should attach a code-challenge instruction. Returns true iff:

creationell_captcha_should_issue_code_challenge() : bool
  1. the master toggle is on, AND
  2. PHP-GD is available, AND
  3. at least one of the three trigger conditions matches (under-attack, ratelimit threshold, watch-list).
Return values
bool

creationell_captcha_code_charset()

Returns the active charset string for the configured option.

creationell_captcha_code_charset(string $charset_key) : string
Parameters
$charset_key : string

One of: digits / alphanumeric / alphanumeric-no-confusing.

Return values
string

creationell_captcha_generate_code()

Generates a fresh random code from the configured charset.

creationell_captcha_generate_code() : string
Return values
string

creationell_captcha_code_token_issue()

Issues a token backed by a server-side WP transient that stores the expected code for at most $expiry_seconds. Returns the opaque ID that `/code-image` and `/code-verify` use to look the code up again.

creationell_captcha_code_token_issue(string $code, int $expiry_seconds) : string

The code is intentionally NOT encoded into the token itself — a base64 round-trip would leak the code to anyone who can read the network response (defeats the OCR-resistant captcha goal). Server state via WP transients is the accepted trade-off.

Parameters
$code : string

The expected code (already from generator).

$expiry_seconds : int

Seconds until the token expires.

Return values
string

creationell_captcha_code_token_verify()

Looks up the code for a token and returns it, or null on: - malformed token (not 32 hex chars) - missing transient (expired or unknown)

creationell_captcha_code_token_verify(string $token[, bool $consume = false ]) : string|null
Parameters
$token : string

The 32-hex-char ID from code_token_issue.

$consume : bool = false

Delete the transient after successful lookup (single-use semantics). The /code-image handler passes false; /code-verify passes true ONLY after a successful code match so retries on wrong input still work.

Return values
string|null

creationell_captcha_rest_code_image()

Handles GET /code-image?t=<token>. Looks up the code from the token (server-side transient), renders the PNG, returns 410 on token failure.

creationell_captcha_rest_code_image(WP_REST_Request $request) : WP_REST_Response

Idempotent — the transient is NOT consumed here so the browser may reload the image.

Parameters
$request : WP_REST_Request

The REST request. Required query parameter t (opaque server-issued token).

Return values
WP_REST_Response

200 with image/png body on success; 410 when the token is unknown/expired or PHP-GD is unavailable.

creationell_captcha_rest_code_verify()

Handles POST /code-verify. Two body shapes:

creationell_captcha_rest_code_verify(WP_REST_Request $request) : WP_REST_Response
  • Code-Challenge mode: { "code": "", "payload": "" } The widget rendered a code-image because the /challenge response embedded data.ccode. Token lookup → case-insensitive match → single-use consume → fresh signed payload.

  • Plain server-verify mode: { "payload": "" } (no code) ALTCHA's widget posts here unconditionally whenever verifyUrl is set (see widget.js logic: verifyUrl ? _e() : verified()). Structural verify on the incoming payload + single-use replay guard on its signature + fresh signed payload back. The replay guard matters: without it a single solved PoW could be amplified into N fresh payloads, undercutting Engine::verify()'s per-form single-use protection.

Parameters
$request : WP_REST_Request

The REST request with JSON body {payload: string, code?: string}.

Return values
WP_REST_Response

200 on success ({payload, verified: true}); 400 on malformed body; 401 on wrong code; 410 on missing/expired/replayed payload or token; 500 on internal error.

creationell_captcha_register_code_challenge_routes()

Registers the two code-challenge REST routes. The /challenge handler itself stays in includes/rest.php; Task 11 extends it with the codeChallenge field and the data.ccode embed.

creationell_captcha_register_code_challenge_routes() : void

creationell_captcha_register_email_obfuscation()

Registers email obfuscation on `init`. The decoder script is always registered; then, unless the kill-switch is set or the feature is off, the configured mode is wired up — the content filters (module 7) or the full-page output buffer (module 8).

creationell_captcha_register_email_obfuscation() : void

creationell_captcha_register_email_buffer()

Wires up the full-page-buffer mode: on `template_redirect` for non-feed front-end requests it enqueues the decoder script and starts an output buffer whose callback obfuscates the page body at flush time.

creationell_captcha_register_email_buffer(EmailObfuscator $obfuscator) : void
Parameters
$obfuscator : EmailObfuscator

The obfuscator.

creationell_captcha_run_firewall()

Runs the IP/user-agent firewall. Hooked on `init` at priority 0 so it fires before the rate limiter, the interceptor and any form-processing handler.

creationell_captcha_run_firewall() : void

creationell_captcha_comments_active()

Whether comment protection applies to the current request.

creationell_captcha_comments_active() : bool
Return values
bool

creationell_captcha_comments_render()

Injects the widget just above the comment form submit button.

creationell_captcha_comments_render(string $submit_field) : string
Parameters
$submit_field : string

The submit button field HTML.

Return values
string

creationell_captcha_comments_verify()

Verifies the captcha before a comment is accepted.

creationell_captcha_comments_verify(array<string, mixed> $commentdata) : array<string, mixed>
Parameters
$commentdata : array<string, mixed>

Comment data.

Return values
array<string, mixed>

creationell_captcha_login_enabled()

Whether login protection is enabled.

creationell_captcha_login_enabled() : bool
Return values
bool

creationell_captcha_login_render()

Renders the widget inside the login form.

creationell_captcha_login_render() : void

creationell_captcha_login_verify()

Verifies the captcha during an interactive login.

creationell_captcha_login_verify(WP_User|WP_Error|null $user, string $username, string $password) : WP_User|WP_Error|null
Parameters
$user : WP_User|WP_Error|null

Authenticated user or error.

$username : string

Submitted username.

$password : string

Submitted password.

Return values
WP_User|WP_Error|null

creationell_captcha_password_reset_enabled()

Whether password-reset protection is enabled.

creationell_captcha_password_reset_enabled() : bool
Return values
bool

creationell_captcha_password_reset_render()

Renders the widget inside the lost-password form.

creationell_captcha_password_reset_render() : void

creationell_captcha_password_reset_verify()

Verifies the captcha during a password-reset request.

creationell_captcha_password_reset_verify(WP_Error $errors) : void
Parameters
$errors : WP_Error

Password-reset errors (passed by WordPress >= 5.4).

creationell_captcha_registration_enabled()

Whether registration protection is enabled.

creationell_captcha_registration_enabled() : bool
Return values
bool

creationell_captcha_registration_render()

Renders the widget inside the registration form.

creationell_captcha_registration_render() : void

creationell_captcha_registration_verify()

Verifies the captcha during registration.

creationell_captcha_registration_verify(WP_Error $errors, string $sanitized_user_login, string $user_email) : WP_Error
Parameters
$errors : WP_Error

Registration errors.

$sanitized_user_login : string

Submitted user login.

$user_email : string

Submitted user email.

Return values
WP_Error

creationell_captcha_resolve_widget_locale()

Resolves the active WordPress locale to a vendored ALTCHA locale code.

creationell_captcha_resolve_widget_locale() : string|null

Returns the locale string (e.g. "de", "fr-fr", "pt-br") if a mapping exists, or null when the WP locale is not in the vendor set — in which case the widget renderer skips both the language attribute and the i18n script enqueue, letting the widget fall through to its own detection (which has only the EN built-in available).

Two filters are applied: creationell_captcha_widget_locale_map to extend / override the lookup table, and creationell_captcha_widget_locale for last-mile overrides after lookup.

Tags
since
0.27.0
Return values
string|null

Vendored ALTCHA locale code or null.

creationell_captcha_get_default_settings()

Default plugin settings.

creationell_captcha_get_default_settings() : array<string, mixed>
Return values
array<string, mixed>

creationell_captcha_get_settings()

Current plugin settings, merged over the defaults.

creationell_captcha_get_settings([bool $force_refresh = false ]) : array<string, mixed>

Memoised for the duration of the request — get_option() itself is cheap thanks to WP's object cache, but the defaults-merge over ~70 keys adds up across the 10+ call sites per request (Interceptor, Firewall, Rate- Limiter, Under-Attack, every form integration). The cache is invalidated automatically when the option is added, updated or deleted.

Parameters
$force_refresh : bool = false

Re-read from the DB even if a cached copy exists. Used by the invalidation hook.

Return values
array<string, mixed>

creationell_captcha_invalidate_settings_cache()

Drops the in-request settings cache. Wired to the option-change hooks below so callers that read settings after an update see the fresh value.

creationell_captcha_invalidate_settings_cache() : void

creationell_captcha_is_disabled()

Whether the captcha is globally disabled via the wp-config constant.

creationell_captcha_is_disabled() : bool
Return values
bool

creationell_captcha_sodium_available()

Whether ext-sodium (required for Argon2id) is available.

creationell_captcha_sodium_available() : bool
Return values
bool

creationell_captcha_generate_secrets()

Generates both HMAC secrets and persists them (non-autoloaded).

creationell_captcha_generate_secrets() : array{signature: string, key_signature: string}
Return values
array{signature: string, key_signature: string}

creationell_captcha_get_secret()

Returns a stored HMAC secret, generating + persisting it on first use.

creationell_captcha_get_secret(string $which) : string
Parameters
$which : string

Either 'signature' or 'key_signature'.

Return values
string

creationell_captcha_get_hmac_secret()

The HMAC signature secret (signs each challenge).

creationell_captcha_get_hmac_secret() : string

A wp-config constant takes precedence over the stored option.

Return values
string

creationell_captcha_get_hmac_key_secret()

The HMAC key-signature secret (enables the fast verification path).

creationell_captcha_get_hmac_key_secret() : string

A wp-config constant takes precedence over the stored option.

Return values
string

creationell_captcha_engine()

Shared captcha engine instance.

creationell_captcha_engine() : Engine
Return values
Engine

creationell_captcha_log()

Write a message to the debug log when CREATIONELL_CAPTCHA_DEBUG is active.

creationell_captcha_log(string $message) : void
Parameters
$message : string

Message to log.

creationell_captcha_get_client_ip()

Resolves the client IP address.

creationell_captcha_get_client_ip() : string

Returns the validated REMOTE_ADDR by default. When the firewall_behind_proxy setting is on, the configured forwarded header is used instead — falling back to REMOTE_ADDR if it yields no valid IP.

Return values
string

creationell_captcha_ip_in_list()

Whether an IP matches any entry in a list of IPs or CIDR ranges.

creationell_captcha_ip_in_list(string $ip, mixed $list) : bool
Parameters
$ip : string

The client IP.

$list : mixed

A list of IPs / CIDR ranges (non-arrays are ignored).

Return values
bool

creationell_captcha_ip_in_cidr()

Whether an IP falls within a CIDR range. Supports IPv4 and IPv6.

creationell_captcha_ip_in_cidr(string $ip, string $cidr) : bool
Parameters
$ip : string

The client IP.

$cidr : string

A CIDR range, e.g. "203.0.113.0/24".

Return values
bool

creationell_captcha_is_valid_ip_or_cidr()

Whether a string is a valid IP address or CIDR range (IPv4 or IPv6).

creationell_captcha_is_valid_ip_or_cidr(string $entry) : bool
Parameters
$entry : string

The candidate string.

Return values
bool

creationell_captcha_wildcard_match()

Whether a subject matches any of the given wildcard patterns (case-insensitive).

creationell_captcha_wildcard_match(string $subject, mixed $patterns) : bool

The pattern alphabet is the same as the firewall UA-blocklist: * is the single wildcard, everything else is matched literally.

Parameters
$subject : string

The string to test.

$patterns : mixed

A list of patterns; non-arrays return false.

Return values
bool

creationell_captcha_private_ranges()

Returns the canonical list of private/loopback CIDR ranges used when the `firewall_trust_private_ranges` toggle is active.

creationell_captcha_private_ranges() : array<string|int, string>
Return values
array<string|int, string>

creationell_captcha_trusted_proxies_constant()

Reads the optional `CREATIONELL_CAPTCHA_TRUSTED_PROXIES` wp-config constant as a list. Accepts either a string array or a comma/whitespace-separated scalar; invalid entries are dropped.

creationell_captcha_trusted_proxies_constant() : array<string|int, string>
Return values
array<string|int, string>

creationell_captcha_is_trusted_proxy()

Whether the given IP belongs to a trusted upstream proxy.

creationell_captcha_is_trusted_proxy(string $ip) : bool

Sources are checked in this order; the first match wins:

  1. firewall_trusted_proxies (the explicit textarea list)
  2. CREATIONELL_CAPTCHA_TRUSTED_PROXIES (wp-config constant)
  3. firewall_trust_private_ranges (when on): the private/loopback ranges
  4. firewall_trust_cloudflare (when on): the cached/bundled CF ranges
Parameters
$ip : string

A validated client IP address.

Return values
bool

creationell_captcha_evaluate_bypass()

Pure bypass evaluator — checks the three bypass sources against the supplied inputs without touching $_SERVER, $_COOKIE or any static cache. The caller is responsible for providing the values.

creationell_captcha_evaluate_bypass(string|null $ip, string|null $ua, array<string, string> $cookies) : array{reason: string, source: string}|false

Sources are checked in this order; the first match wins:

  1. firewall_ip_allow vs $ip
  2. bypass_ua_allow vs $ua
  3. bypass_cookies vs $cookies (strict name=value)
Parameters
$ip : string|null

Client IP, or null to skip the IP check.

$ua : string|null

User-Agent, or null to skip the UA check.

$cookies : array<string, string>

Cookie map (name => value).

Return values
array{reason: string, source: string}|false

creationell_captcha_request_bypassed()

Whether the current request is allowed to bypass captcha, under-attack and firewall protections. Reads $_SERVER, $_COOKIE and the request's client IP, then delegates to `creationell_captcha_evaluate_bypass()`.

creationell_captcha_request_bypassed() : array{reason: string, source: string}|false

Result is memoised for the request — settings, IP and cookies do not change within a single PHP request. Only reason flows into the event-log context; source is exposed for diagnostic logging by callers.

Return values
array{reason: string, source: string}|false

creationell_captcha_validate_action_pattern()

Validates a single interceptor-action pattern.

creationell_captcha_validate_action_pattern(string $entry) : string|null

Allowed: lowercase/uppercase letters, digits, _, -, * (wildcard), with an optional leading ! for exclusion patterns. Empty input or patterns of only ! are rejected.

Parameters
$entry : string

Raw entry (already trimmed by the caller).

Return values
string|null

Normalised entry, or null if invalid.

creationell_captcha_validate_cookie_entry()

Validates a single bypass-cookie entry of the form `name=value`.

creationell_captcha_validate_cookie_entry(string $entry) : string|null

Name must be alphanumeric, _ or -. Value may be empty and is length-capped to 200 bytes. The returned entry has the value passed through sanitize_text_field().

Parameters
$entry : string

Raw entry (already trimmed by the caller).

Return values
string|null

Normalised name=value entry, or null if invalid.

creationell_captcha_anonymize_ip()

Truncates an IP for DSGVO-compliant storage. IPv4 → last octet zeroed, IPv6 → last 80 bits zeroed. Invalid IPs return ''.

creationell_captcha_anonymize_ip(string $ip) : string
Parameters
$ip : string

A validated client IP address.

Return values
string

creationell_captcha_request_body_fingerprint()

Returns a JSON-encoded fingerprint of $_POST: { field-name: value-byte-length }.

creationell_captcha_request_body_fingerprint() : string

No values are recorded — only structural metadata for attack-pattern diagnosis. Field names that contain known sensitive substrings (password, iban, api_key, …) are replaced with [masked:<8-char-sha256>] so the fingerprint does not leak custom-form schema (e.g. bank_iban_input). Output is length-capped to 2048 bytes; if longer, the JSON is collapsed to "}" rather than truncated mid-entry.

Return values
string

creationell_captcha_block_response()

Sends a fail-closed block response and terminates the request.

creationell_captcha_block_response(int $status, string $message[, int $retry_after = 0 ]) : void
Parameters
$status : int

HTTP status code (403 firewall, 429 rate limit).

$message : string

The message shown to the client.

$retry_after : int = 0

Optional Retry-After value in seconds.

creationell_captcha_base64url_encode()

Base64URL encoder (RFC 4648 §5) — strips standard-base64 padding and replaces +/ with -_ so the value is URL-safe.

creationell_captcha_base64url_encode(string $bytes) : string
Parameters
$bytes : string

Raw bytes to encode.

Return values
string

creationell_captcha_base64url_decode()

Base64URL decoder — accepts unpadded URL-safe input and returns the raw bytes. Returns the empty string on malformed input (no exceptions).

creationell_captcha_base64url_decode(string $encoded) : string
Parameters
$encoded : string

URL-safe base64 string.

Return values
string

creationell_captcha_ratelimit_current_count()

Reads the current rate-limit counter for an IP without incrementing it.

creationell_captcha_ratelimit_current_count(string $ip) : int

Uses the same bucket key as Creationell\Captcha\RateLimiter::run() so the value matches what the run-loop would see. Returns 0 if no transient exists for the current window.

Parameters
$ip : string

Client IP (call creationell_captcha_get_client_ip()).

Return values
int

creationell_captcha_cf7_active()

Whether the Contact Form 7 integration is active.

creationell_captcha_cf7_active() : bool
Return values
bool

creationell_captcha_cf7_register_tag()

Registers the [creationell_captcha] Contact Form 7 form-tag.

creationell_captcha_cf7_register_tag() : void

Registered unconditionally (no creationell_captcha_cf7_active() guard) so CF7 always recognises the tag and never prints it as raw text; the tag handler returns an empty string when the integration is inactive.

creationell_captcha_cf7_tag_handler()

Renders the widget for the [creationell_captcha] form-tag.

creationell_captcha_cf7_tag_handler() : string
Return values
string

creationell_captcha_cf7_auto_inject()

Auto-injects the widget into CF7 forms without a [creationell_captcha] tag.

creationell_captcha_cf7_auto_inject(string $elements) : string
Parameters
$elements : string

The form's inner HTML.

Return values
string

creationell_captcha_cf7_verify()

Verifies the captcha on a Contact Form 7 submission.

creationell_captcha_cf7_verify(mixed $spam, mixed $submission) : bool

Hooked on wpcf7_spam: returning true marks the submission as spam, which CF7 then rejects through its standard flow.

Parameters
$spam : mixed

Whether CF7 already classified the submission as spam.

$submission : mixed

The WPCF7_Submission object.

Return values
bool

creationell_captcha_forminator_active()

Whether the Forminator integration is active.

creationell_captcha_forminator_active() : bool
Return values
bool

creationell_captcha_forminator_inject()

Auto-injects the widget before the submit button of a Forminator custom form.

creationell_captcha_forminator_inject(mixed $html, mixed $form_id) : string

The forminator_render_form_submit_markup filter also fires for polls and quizzes; injection is restricted to the forminator_forms post type.

Parameters
$html : mixed

The submit-section HTML.

$form_id : mixed

The form's post ID.

Return values
string

creationell_captcha_forminator_verify()

Verifies the captcha on a Forminator custom-form submission.

creationell_captcha_forminator_verify(mixed $errors) : array<int, array<string, string>>

Hooked on forminator_custom_form_submit_errors (custom forms only): a non-empty errors array makes Forminator reject the submission.

Parameters
$errors : mixed

The current array of submission errors.

Return values
array<int, array<string, string>>

creationell_captcha_woocommerce_active()

Whether any WooCommerce protection applies right now.

creationell_captcha_woocommerce_active() : bool

Shared gate that the per-form predicates _wc_*_active() route through — encapsulates the kill-switch, the class_exists check and the master toggle so each form predicate just needs to add its own sub-toggle check.

Return values
bool

creationell_captcha_wc_checkout_active()

Whether the WooCommerce checkout protection is active.

creationell_captcha_wc_checkout_active() : bool
Return values
bool

creationell_captcha_wc_checkout_render()

Renders the widget directly before the Place-Order button on the checkout.

creationell_captcha_wc_checkout_render() : void

creationell_captcha_wc_checkout_verify()

Verifies the captcha during checkout validation.

creationell_captcha_wc_checkout_verify(array<string, mixed> $data, mixed $errors) : void

woocommerce_after_checkout_validation fires inside WooCommerce's process_checkout() after all other validation has run; adding an error to the passed-through WP_Error aborts the order.

Parameters
$data : array<string, mixed>

Posted checkout data (unused).

$errors : mixed

The checkout WP_Error (passed by reference of the object).

creationell_captcha_wc_login_active()

Whether the WooCommerce my-account login protection is active.

creationell_captcha_wc_login_active() : bool
Return values
bool

creationell_captcha_wc_login_render()

Renders the widget at the bottom of the WooCommerce login form.

creationell_captcha_wc_login_render() : void

creationell_captcha_wc_login_verify()

Verifies the captcha on a WooCommerce my-account login submission.

creationell_captcha_wc_login_verify(mixed $validation_error, string $username, string $password) : mixed

Returns a WP_Error to fail the login; otherwise returns the incoming $validation_error value unchanged (so other filters can keep working).

Parameters
$validation_error : mixed

The current validation error (WP_Error|null|false).

$username : string

Submitted username (unused).

$password : string

Submitted password (unused).

creationell_captcha_wc_registration_active()

Whether the WooCommerce registration protection is active.

creationell_captcha_wc_registration_active() : bool
Return values
bool

creationell_captcha_wc_registration_render()

Renders the widget at the bottom of the WooCommerce registration form.

creationell_captcha_wc_registration_render() : void

creationell_captcha_wc_registration_verify()

Verifies the captcha during WooCommerce my-account registration.

creationell_captcha_wc_registration_verify(mixed $errors, string $username, string $email) : mixed
Parameters
$errors : mixed

The current WP_Error carrier from WooCommerce.

$username : string

Submitted username (unused).

$email : string

Submitted email (unused).

creationell_captcha_wc_lost_password_active()

Whether the WooCommerce lost-password render is active.

creationell_captcha_wc_lost_password_active() : bool
Return values
bool

creationell_captcha_wc_lost_password_render()

Renders the widget inside the WooCommerce lost-password form.

creationell_captcha_wc_lost_password_render() : void

creationell_captcha_wpforms_active()

Whether the WPForms integration is active.

creationell_captcha_wpforms_active() : bool
Return values
bool

creationell_captcha_wpforms_inject()

Auto-injects the widget directly before the WPForms submit button.

creationell_captcha_wpforms_inject(array<string, mixed> $form_data, mixed $form) : void

Fires inside the element, so the hidden altcha input that the widget emits is part of the WPForms submission.

Parameters
$form_data : array<string, mixed>

WPForms form configuration.

$form : mixed

WPForms form post (unused).

creationell_captcha_wpforms_verify()

Verifies the captcha on a WPForms submission.

creationell_captcha_wpforms_verify(array<int, mixed> $fields, array<string, mixed> $entry, array<string, mixed> $form_data) : void

Hooked on wpforms_process (action). On failure we set an entry in wpforms()->process->errors[ $form_id ]['header'] — WPForms then renders the message above the form and refuses to save the entry.

Parameters
$fields : array<int, mixed>

Sanitized field values (unused).

$entry : array<string, mixed>

Raw $_POST['wpforms'] (unused).

$form_data : array<string, mixed>

Form configuration.

creationell_captcha_interceptor_inject_buffer_start()

Conditionally starts the output buffer on template_redirect priority 0.

creationell_captcha_interceptor_inject_buffer_start() : void

The buffer only runs when (a) the master interceptor toggle is on, (b) at least one inject path is configured, AND (c) the current request path matches that pattern list. On non-matching pages the request is unaffected.

creationell_captcha_interceptor_inject_buffer()

Buffer callback. Replaces every `<form …>…</form>` with the same form plus an `<altcha-widget>` inserted directly before `</form>`. Idempotent — forms that already contain `<altcha-widget` are returned unchanged.

creationell_captcha_interceptor_inject_buffer(string $html) : string
Parameters
$html : string

Full page HTML.

Return values
string

creationell_captcha_run_interceptor()

Runs the request interceptor. Hooked on `init` at priority 1 so it fires before any form-processing handler.

creationell_captcha_run_interceptor() : void

creationell_captcha_protect_path()

Registers one or more path patterns to be guarded by the interceptor.

creationell_captcha_protect_path(string|array<int, string> $patterns) : void

Developer API — later form-plugin integrations call this to protect their submission endpoints without an admin entering patterns by hand. The patterns are merged into the creationell_captcha_interceptor_paths filter.

Parameters
$patterns : string|array<int, string>

A path pattern or list of patterns.

creationell_captcha_activate()

Runs on plugin activation: seeds default options and HMAC secrets.

creationell_captcha_activate() : void

creationell_captcha_deactivate()

Runs on plugin deactivation: clears scheduled cron slots and lets every module react via the `creationell_captcha_deactivated` action hook.

creationell_captcha_deactivate() : void

creationell_captcha_run_rate_limiter()

Runs the per-IP rate limiter. Hooked on `init` at priority 0; registered after the firewall so the firewall runs first.

creationell_captcha_run_rate_limiter() : void

creationell_captcha_register_rest_routes()

Registers the public challenge route.

creationell_captcha_register_rest_routes() : void

creationell_captcha_rest_challenge()

Returns a fresh, single-use challenge. Records the issuance via the standard event channel — aggregate counters always increment, the detail-log entry is gated by the `log_challenge` per-type toggle from Modul 11c.

creationell_captcha_rest_challenge(WP_REST_Request $request) : WP_REST_Response
Parameters
$request : WP_REST_Request

The REST request. Optional query parameter ctx (HMAC token, used by the under-attack interstitial to suppress the code-challenge attachment).

Return values
WP_REST_Response

JSON challenge envelope with algorithm, challenge, salt, signature, parameters and optional codeChallenge.image URL.

creationell_captcha_canonical_params_json()

Canonical-JSON serialisation of ALTCHA challenge parameters, byte- identical to `altcha-lib-php`'s `ChallengeParameters::toCanonicalJson()` (= ksort top-level + recursive ksort on assoc sub-arrays, JSON-encoded with UNESCAPED_SLASHES | UNESCAPED_UNICODE, null keys dropped).

creationell_captcha_canonical_params_json(array<string, mixed> $params) : string

Needed for the re-sign step in Modul 15's /challenge handler after we mutate parameters.data.ccode.

Parameters
$params : array<string, mixed>

Parameter array from create_challenge().

Return values
string

creationell_captcha_canonical_sort_recursive()

Recursive helper used by `canonical_params_json` — mirrors the lib's `sortRecursive`. List arrays (sequential integer keys) keep their order; associative arrays get `ksort`-ed in place.

creationell_captcha_canonical_sort_recursive(array<string|int, mixed> &$data) : void
Parameters
$data : array<string|int, mixed>

creationell_captcha_list_setting_keys()

Setting keys whose value is a list (every `textarea` field).

creationell_captcha_list_setting_keys() : array<int, string>

Derived from the field specification so the list never drifts. "Load defaults" preserves these keys; "reset" clears them.

Return values
array<int, string>

creationell_captcha_export_settings()

Builds the settings-export payload.

creationell_captcha_export_settings() : array<string, mixed>

The HMAC secrets are deliberately excluded — they must never leave the site.

Return values
array<string, mixed>

creationell_captcha_import_settings()

Validates and applies a settings-export payload.

creationell_captcha_import_settings(array<string, mixed> $payload) : array<string, mixed>|WP_Error

The settings array is run through creationell_captcha_sanitize_settings(), so the same guarantees as the settings form apply: whitelisted selects, clamped numbers, bounded lists, unknown keys dropped, missing keys defaulted.

Parameters
$payload : array<string, mixed>

Decoded export payload.

Return values
array<string, mixed>|WP_Error

On success: { imported, version_notice }.

creationell_captcha_reset_settings()

Full factory reset: writes the complete default settings array, which also empties every list. Secrets, analytics counters and the event log are left untouched.

creationell_captcha_reset_settings() : void

creationell_captcha_load_default_settings()

Resets every non-list setting to its default while preserving the current list values (IP block/allow, UA block, interceptor paths).

creationell_captcha_load_default_settings() : void

creationell_captcha_admin_tabs()

Ordered list of the admin settings tabs.

creationell_captcha_admin_tabs() : array<string, string>

The array key is the tab id; it doubles as the suffix of the Settings-API page slug (creationell-captcha-tab-<id>) that do_settings_sections() uses.

Return values
array<string, string>

Tab id => visible label.

creationell_captcha_admin_sections()

Settings sections and the tab each one belongs to.

creationell_captcha_admin_sections() : array<string, array<string, string>>

Section order within a tab follows this array's order.

Return values
array<string, array<string, string>>

Section id => { tab, title, callback }.

creationell_captcha_settings_fields()

Field specification for the captcha settings.

creationell_captcha_settings_fields() : array<string, array<string, mixed>>

Every field carries a section key naming the section (and thereby the tab) it renders in; the section ids match creationell_captcha_admin_sections().

Return values
array<string, array<string, mixed>>

creationell_captcha_register_settings()

Registers the plugin setting, the per-tab sections and the fields.

creationell_captcha_register_settings() : void

creationell_captcha_sanitize_settings()

Sanitises the settings array before it is stored.

creationell_captcha_sanitize_settings(mixed $input) : array<string, mixed>
Parameters
$input : mixed

Raw input from the settings form.

Return values
array<string, mixed>

creationell_captcha_render_engine_section()

Renders the description shown at the top of the Proof-of-Work-Engine section.

creationell_captcha_render_engine_section() : void

creationell_captcha_render_widget_appearance_section()

Renders the description shown at the top of the widget-appearance section.

creationell_captcha_render_widget_appearance_section() : void

creationell_captcha_render_code_challenge_section()

Renders the description shown at the top of the code-challenge section.

creationell_captcha_render_code_challenge_section() : void

Includes a warning notice when the PHP-GD extension is missing — without it, image rendering cannot work and the trigger logic stays disabled.

creationell_captcha_render_core_forms_section()

Renders the description shown at the top of the core-forms section.

creationell_captcha_render_core_forms_section() : void

creationell_captcha_render_interceptor_section()

Renders the description shown at the top of the interceptor section.

creationell_captcha_render_interceptor_section() : void

creationell_captcha_render_form_plugins_section()

Renders the description shown at the top of the form-plugins section.

creationell_captcha_render_form_plugins_section() : void

When no supported form plugin is active the section has no fields, so the description doubles as a hint.

creationell_captcha_render_proxy_section()

Renders the description shown at the top of the proxy section.

creationell_captcha_render_proxy_section() : void

creationell_captcha_render_bypass_section()

Renders the description shown at the top of the bypass section.

creationell_captcha_render_bypass_section() : void

creationell_captcha_render_firewall_section()

Renders the description shown at the top of the firewall section.

creationell_captcha_render_firewall_section() : void

creationell_captcha_render_ratelimit_section()

Renders the description shown at the top of the rate-limiting section.

creationell_captcha_render_ratelimit_section() : void

creationell_captcha_render_underattack_section()

Renders the description shown at the top of the under-attack section.

creationell_captcha_render_underattack_section() : void

creationell_captcha_render_underattack_appearance_section()

Renders the description shown at the top of the under-attack appearance section.

creationell_captcha_render_underattack_appearance_section() : void

creationell_captcha_render_analytics_section()

Renders the description shown at the top of the analytics section.

creationell_captcha_render_analytics_section() : void

creationell_captcha_render_email_section()

Renders the description shown at the top of the email-protection section.

creationell_captcha_render_email_section() : void

creationell_captcha_render_field()

Renders a single settings field.

creationell_captcha_render_field(array<string, mixed> $args) : void
Parameters
$args : array<string, mixed>

Field arguments (key + field spec).

creationell_captcha_tools_redirect()

Stores a one-shot admin notice and redirects back to the Werkzeuge page.

creationell_captcha_tools_redirect(string $type, string $message) : never
Parameters
$type : string

'success' or 'error'.

$message : string

Notice text.

Return values
never

creationell_captcha_tools_guard()

Guards a tools action: requires manage_options and a valid nonce.

creationell_captcha_tools_guard(string $action) : void
Parameters
$action : string

The nonce action name.

creationell_captcha_handle_export_settings()

Streams the current settings as a JSON download.

creationell_captcha_handle_export_settings() : void

creationell_captcha_handle_import_settings()

Handles the settings-import upload.

creationell_captcha_handle_import_settings() : void

creationell_captcha_handle_reset_settings()

Handles the full factory reset.

creationell_captcha_handle_reset_settings() : void

creationell_captcha_handle_load_defaults()

Handles "load defaults" (keeps the lists).

creationell_captcha_handle_load_defaults() : void

creationell_captcha_handle_cloudflare_refresh()

Triggers a manual Cloudflare-range refresh from the Werkzeuge page.

creationell_captcha_handle_cloudflare_refresh() : void

creationell_captcha_handle_cloudflare_clear()

Empties the cached Cloudflare-range option from the Werkzeuge page.

creationell_captcha_handle_cloudflare_clear() : void

creationell_captcha_register_tools_page()

Registers the "Werkzeuge" submenu page under the CreaCaptcha menu.

creationell_captcha_register_tools_page() : void

creationell_captcha_render_tools_notice()

Renders the one-shot admin notice left behind by a tools action.

creationell_captcha_render_tools_notice() : void

creationell_captcha_render_tools_page()

Renders the "Werkzeuge" page.

creationell_captcha_render_tools_page() : void

creationell_captcha_render_cloudflare_status()

Renders the Cloudflare-cache status block inside the Werkzeuge tool card.

creationell_captcha_render_cloudflare_status() : void

creationell_captcha_run_under_attack()

Runs the under-attack interstitial gate for front-end page views. Hooked on `template_redirect` — fires only for front-end requests, so wp-admin, wp-login.php, REST and cron are inherently exempt.

creationell_captcha_run_under_attack() : void

creationell_captcha_maybe_upgrade()

Runs schema migrations when the stored version differs from the running one.

creationell_captcha_maybe_upgrade() : void

Hooked on admin_init. When the event-log table already exists it is re-run through dbDelta so new columns are added; a missing table is left alone — it is created on demand when the event log is switched on.

creationell_captcha_migrate_widget_mode()

Migrates the legacy `widget_mode` setting (Modul 11a) to the new `widget_display` + `widget_auto_trigger` pair (Modul 14). Idempotent — if `widget_display` is already present in the stored option, the migration is skipped.

creationell_captcha_migrate_widget_mode() : void

Mapping: visible → widget_display=standard, widget_auto_trigger=none auto → widget_display=invisible, widget_auto_trigger=onload overlay → widget_display=floating, widget_auto_trigger=onsubmit

The legacy widget_mode key is removed from the option once the new keys are in place.

creationell_captcha_register_assets()

Registers the widget script and — for Argon2id — its worker registration.

creationell_captcha_register_assets() : void

creationell_captcha_build_widget_markup()

Builds the ALTCHA widget markup as a plain string. Enqueues the widget script as a side effect.

creationell_captcha_build_widget_markup() : string

Safe to call from inside an ob_start callback because it does not use output-buffering itself — unlike the legacy creationell_captcha_get_widget_markup wrapper that this function now powers.

Reads eight widget-customization settings (display, type, auto_trigger, theme, hide_branding, primary_color, custom_css, strings_override) and maps them to the corresponding v3 attributes. Boolean attributes are emitted as empty-string values per HTML5 convention.

Return values
string

creationell_captcha_render_widget()

Renders the ALTCHA widget markup and enqueues its assets.

creationell_captcha_render_widget() : void

creationell_captcha_verify_payload()

Verifies a raw base64 ALTCHA payload string.

creationell_captcha_verify_payload(string $raw) : bool

Shared by the POST-based request helper and the third-party form integrations, which read the payload from their plugin's submission data.

Parameters
$raw : string

The raw altcha payload.

Return values
bool

creationell_captcha_verify_request()

Reads and verifies the ALTCHA payload from the current POST request.

creationell_captcha_verify_request() : bool

The ALTCHA payload itself is the anti-bot token — no separate WordPress nonce applies here.

Return values
bool

creationell_captcha_widget()

Public template tag — renders the ALTCHA widget.

creationell_captcha_widget() : void

For use in theme templates or custom-form markup; the call must sit inside the element so the hidden altcha field is submitted with the form.

creationell_captcha_get_widget_markup()

Returns the ALTCHA widget markup as a string.

creationell_captcha_get_widget_markup() : string

Used by the shortcode and by the third-party form integrations, which embed the widget into another plugin's form markup. Implementation routes through the underlying string builder rather than ob_start so the function is safe to call from inside other output-buffer callbacks (e.g. Modul 12's auto-inject buffer).

Return values
string

The widget markup.

creationell_captcha_widget_shortcode()

Shortcode handler for [creationell_captcha].

creationell_captcha_widget_shortcode() : string

Place the shortcode inside a element so the hidden altcha field is submitted with the form.

Return values
string

The widget markup.

Search results