CreaCaptcha

settings.php

Settings registration via the WordPress Settings API.

Table of Contents

Constants

CREATIONELL_CAPTCHA_SANITIZE_FORM  = 'form'
Sanitiser context: the settings form (`options.php`).
CREATIONELL_CAPTCHA_SANITIZE_PROGRAMMATIC  = 'programmatic'
Sanitiser context: programmatischer Schreibvorgang (Import, Werksreset, „Standardwerte laden", WP-CLI).
CREATIONELL_CAPTCHA_SANITIZE_RESET  = 'reset'
Sanitiser context: Werksreset (`creationell_captcha_reset_settings()`).

Functions

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_context()  : string|null
Liest — und setzt optional — den angehefteten Sanitizer-Kontext.
creationell_captcha_with_sanitize_context()  : mixed
Führt $callback aus, während der Sanitizer-Kontext auf $context festgelegt ist.
creationell_captcha_sanitize_settings_option()  : array<string, mixed>
Einstiegspunkt des `sanitize_option_creationell_captcha_settings`-Filters.
creationell_captcha_truncate_setting_text()  : string
Kürzt einen Einstellungswert auf höchstens $max_chars Zeichen und garantiert gültiges UTF-8.
creationell_captcha_truncate_chars()  : string
Kürzt gültiges UTF-8 ohne mbstring auf $max_chars ZEICHEN.
creationell_captcha_truncate_chars_by_bytes()  : string
Dritte und letzte Kürzungsstufe: zählt UTF-8-Startbytes.
creationell_captcha_sanitize_settings()  : array<string, mixed>
Sanitises the settings array before it is stored.
creationell_captcha_sync_event_log_table()  : void
Legt die Ereignis-Log-Tabelle an, sobald das Detail-Log eingeschaltet GESPEICHERT wurde.
creationell_captcha_store_settings()  : void
Der eine Schreibweg des Plugins auf `creationell_captcha_settings`.
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_field_label()  : string
Liefert das Label eines Einstellungsfeldes (Fallback: der Schlüssel selbst).
creationell_captcha_field_spec()  : array<string, array<string, mixed>>
Request-lokal gehaltene Feldspezifikation für die beiden Label-Helfer.
creationell_captcha_field_option_label()  : string
Liefert das Options-Label eines `select`-Feldes (Fallback: der Rohwert).

Constants

CREATIONELL_CAPTCHA_SANITIZE_FORM

Sanitiser context: the settings form (`options.php`).

public mixed CREATIONELL_CAPTCHA_SANITIZE_FORM = 'form'

Ein disabled-Input sendet beim Absenden keinen Wert — deshalb (und NUR deshalb) schreibt der Sanitizer in diesem Kontext gegatete Felder aus dem gespeicherten Zustand zurück.

CREATIONELL_CAPTCHA_SANITIZE_PROGRAMMATIC

Sanitiser context: programmatischer Schreibvorgang (Import, Werksreset, „Standardwerte laden", WP-CLI).

public mixed CREATIONELL_CAPTCHA_SANITIZE_PROGRAMMATIC = 'programmatic'

Hier ist der übergebene Wert eine vollständige, bewusste Angabe; eine Rückschreibung aus dem Altzustand würde sie still überstimmen (AF-1/AF-3).

CREATIONELL_CAPTCHA_SANITIZE_RESET

Sanitiser context: Werksreset (`creationell_captcha_reset_settings()`).

public mixed CREATIONELL_CAPTCHA_SANITIZE_RESET = 'reset'

Wie PROGRAMMATIC — plus die eine Zusage, die den Werksreset von jedem anderen Schreibvorgang unterscheidet: KEIN gespeicherter Schlüssel wird übernommen, auch keiner ausserhalb der aktuellen Feldspezifikation.

Warum das ein eigener Wert sein muss (Nachlese N6, Befund 5): Die Übernahme-Schleife am Ende von creationell_captcha_sanitize_settings() hält gespeicherte Schlüssel fest, die creationell_captcha_settings_fields() gerade nicht liefert — die Schalter der Formular-Plugins hängen an class_exists(), sind bei deaktiviertem Plugin also nicht in der Spezifikation. Für jeden regulären Schreibvorgang ist das richtig (sonst löschte ein Speichern der Einstellungsseite den Schalter eines gerade deaktivierten Plugins). Für den dokumentierten „vollen Werksreset" ist es falsch: wp creacaptcha settings reset --yes meldete „Auf Werkseinstellungen zurückgesetzt", während ein protect_wpforms => false aus der Zeit vor der Deaktivierung — oder ein beliebiger Fremdschlüssel aus wp option patch/DB-Restore — die Option unverändert überlebte.

Der Wert ersetzt PROGRAMMATIC ausschliesslich beim Reset. Import, „Standardwerte laden", WP-CLI-Schreibvorgänge und die Listen-Befehle bleiben auf PROGRAMMATIC: sie übergeben zwar ebenfalls einen vollständigen Wertesatz, sind aber kein Werksreset und dürfen den Schalter eines gerade inaktiven Formular-Plugins nicht wegräumen.

Tags
since
1.1.0

Functions

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

Liest — und setzt optional — den angehefteten Sanitizer-Kontext.

creationell_captcha_sanitize_context([string|false|null $set = false ]) : string|null

Der Kontext wird bewusst EXPLIZIT gesetzt und nicht aus is_admin(), admin_init oder ähnlichen Umgebungsindizien erraten: genau dieses Raten ist die Wurzel der Kartenwidersprüche W1/W2 der Befunddatei (ein Menüpunkt, zwei Semantiken, je nachdem ob admin_init gefeuert hat).

Parameters
$set : string|false|null = false

FALSE liest nur; ein String oder NULL setzt.

Return values
string|null —

Aktuell angehefteter Kontext oder NULL.

creationell_captcha_with_sanitize_context()

Führt $callback aus, während der Sanitizer-Kontext auf $context festgelegt ist.

creationell_captcha_with_sanitize_context(string $context, callable $callback) : mixed

Nötig, weil register_setting() den Sanitizer zusätzlich als sanitize_option_creationell_captcha_settings-Filter anhängt: jeder update_option()-Aufruf im Admin-Kontext läuft durch ihn hindurch, auch Import und Reset über admin-post.php. Ohne diese Klammer bekämen genau jene Pfade Formular-Semantik.

Parameters
$context : string

Einer der CREATIONELL_CAPTCHA_SANITIZE_*-Werte.

$callback : callable

Auszuführender Schreibvorgang.

Return values
mixed —

Rückgabewert von $callback.

creationell_captcha_sanitize_settings_option()

Einstiegspunkt des `sanitize_option_creationell_captcha_settings`-Filters.

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

Rohwert aus dem Schreibvorgang.

Return values
array<string, mixed>

creationell_captcha_truncate_setting_text()

Kürzt einen Einstellungswert auf höchstens $max_chars Zeichen und garantiert gültiges UTF-8.

creationell_captcha_truncate_setting_text(string $value, int $max_chars) : string

Bewusst zeichen- statt byteorientiert: substr() schnitt bisher mitten in eine Mehrbyte-Sequenz (AF-7). Ungültiges UTF-8 wird entfernt, bevor der Wert in den serialisierten Options-Blob wandert — nicht danach in der DB repariert.

Parameters
$value : string

Bereits vorsanitisierter Wert.

$max_chars : int

Obergrenze in Zeichen (nicht Bytes).

Return values
string

creationell_captcha_truncate_chars()

Kürzt gültiges UTF-8 ohne mbstring auf $max_chars ZEICHEN.

creationell_captcha_truncate_chars(string $value, int $max_chars) : string

Drei Stufen, weil jede einzelne ausfallen kann — und der Ausfall darf den Wert nicht kosten:

  1. preg_match( '/^.{0,N}/us' ) — der schnelle Weg. s lässt „.“ auch Zeilenumbrüche treffen (relevant für textblock).
  2. iconv_substr() — greift, wenn Stufe 1 an einem PCRE-Limit scheitert (Backtrack-Limit, JIT-Stack). iconv ist keine PCRE-Bibliothek und deshalb von diesen Limits nicht betroffen.
  3. Ein Byte-Lauf über die UTF-8-Startbytes — braucht überhaupt keine Erweiterung und keine PCRE.

WARUM ES DIESE FUNKTION GIBT (Nachlese N6, Befund 7; Fehlerklasse 4)

Nach Stufe 1 stand hier bis zur Nachlese return '';. Das war als „lieber ein leeres Feld, das der Betreiber sieht" begründet — nur sieht er es nicht: an dieser Stelle wird keine add_settings_error() erzeugt, das leere Feld ist also genau so still wie die kaputte Sequenz, gegen die die Begründung argumentierte. Und der Sanitizer läuft bei JEDEM Schreibvorgang, auch bei einem, der dieses Feld gar nicht anfasst (Werksreset, „Standardwerte laden", settings set eines anderen Schlüssels, jedes Speichern der Einstellungsseite): ein gespeicherter CSS- oder Übersetzungsblock wäre damit still und vollständig weg gewesen. Der Vorgängerstand vor W2-7 lieferte an dieser Stelle wenigstens den Anfang des Wertes (substr(), byteweise und deshalb möglicherweise mitten in einer Mehrbyte-Sequenz). Beide Stufen unten liefern denselben Anfang, nur an einer ZEICHEN-Grenze — der Datenverlust entfällt, ohne den AF-7-Fehler zurückzuholen.

Vorbedingung: $value ist gültiges UTF-8. Der Aufrufer stellt das her; Stufe 3 verlässt sich darauf, weil sie Startbytes zählt und Fortsetzungsbytes (0x80–0xBF) in gültigem UTF-8 nie an einer Zeichengrenze stehen.

Parameters
$value : string

Gültiges UTF-8.

$max_chars : int

Obergrenze in Zeichen.

Tags
since
1.1.0
Return values
string

creationell_captcha_truncate_chars_by_bytes()

Dritte und letzte Kürzungsstufe: zählt UTF-8-Startbytes.

creationell_captcha_truncate_chars_by_bytes(string $value, int $max_chars) : string

Braucht weder mbstring noch iconv noch PCRE — deshalb steht sie am Ende der Kette in creationell_captcha_truncate_chars(). Eigene Funktion, weil sie sonst auf jedem Rechner mit iconv unerreichbar und damit ungetestet wäre.

Startbytes: 0xxxxxxx = 1 Byte, 110xxxxx = 2, 1110xxxx = 3, 11110xxx = 4. Fortsetzungsbytes (10xxxxxx, 0x80–0xBF) stehen in gültigem UTF-8 nie an einer Zeichengrenze; ungültige Eingaben schliesst der Aufrufer aus (creationell_captcha_truncate_setting_text() prüft und repariert vorher).

Parameters
$value : string

Gültiges UTF-8.

$max_chars : int

Obergrenze in Zeichen.

Tags
since
1.1.0
Return values
string

creationell_captcha_sanitize_settings()

Sanitises the settings array before it is stored.

creationell_captcha_sanitize_settings(mixed $input[, string $context = CREATIONELL_CAPTCHA_SANITIZE_PROGRAMMATIC ]) : array<string, mixed>
Parameters
$input : mixed

Raw input from the settings form.

$context : string = CREATIONELL_CAPTCHA_SANITIZE_PROGRAMMATIC

Schreibkontext, einer der CREATIONELL_CAPTCHA_SANITIZE_*-Werte. Default ist „programmatisch": alle direkten Aufrufer (Import, WP-CLI) übergeben einen vollständigen Wertesatz. Ausgewertet werden ausschließlich die zwei bekannten programmatischen Werte …_PROGRAMMATIC und …_RESET; jeder andere Wert — auch ein unerwarteter, etwa der Optionsname aus einer Legacy-sanitize_option- Registrierung — erhält die verlustfreie Formular-Semantik. …_RESET unterscheidet sich von …_PROGRAMMATIC an genau einer Stelle: er übernimmt auch keine gespeicherten Schlüssel ausserhalb der aktuellen Feldspezifikation (voller Werksreset).

Return values
array<string, mixed>

creationell_captcha_sync_event_log_table()

Legt die Ereignis-Log-Tabelle an, sobald das Detail-Log eingeschaltet GESPEICHERT wurde.

creationell_captcha_sync_event_log_table() : void

E3b — warum das hier hängt und nicht mehr im Sanitizer: Der Sanitizer ist über register_setting() zugleich der sanitize_option-Filter der Option und eine öffentliche, dokumentierte Funktion. Ein ensure_table() in ihm bedeutete DDL für jeden Aufrufer, der nur prüfen, vergleichen oder eine Vorschau bauen will — wp creacaptcha doctor verzichtet deshalb bereits ausdrücklich auf den Sanitizer-Vergleich (Check 9). Die Tabellenanlage gehört an das Ergebnis des Schreibvorgangs; das ist dieselbe Bauform, die creationell_captcha_sync_cloudflare_cron() für den Cron-Slot benutzt.

Reichweite gegenüber vorher:

  • wp-admin (Formular, Import, Werksreset, „Standardwerte laden"): unverändert — die Tabelle entsteht weiterhin beim Speichern.
  • WP-CLI und jeder andere Kontext ohne admin_init: NEU abgedeckt. Dort hing der sanitize_option-Filter gar nicht; wp option update creationell_captcha_settings konnte das Log einschalten, ohne dass je eine Tabelle entstand (die Selbstheilungs-Lücke aus DS-4).
  • Ein Speichern, das den Optionswert unverändert lässt: WordPress schreibt dann nichts und feuert keinen der beiden Hooks. Diese Lücke deckt seit der Nachlese N6 creationell_captcha_store_settings() ab — jeder Plugin-eigene Schreibweg auf die Option ruft die Synchronisierung danach selbst noch einmal auf. Nicht abgedeckt bleibt ein Schreibvorgang an diesen Wegen vorbei (wp option update, DB-Restore) ohne Wertänderung; dafür bleibt wp creacaptcha repair der Weg, auf den Doctor-Check 3 und der Log-Hinweis in Analytics::log_row() verweisen.

DS-2-Grenze: Auslöser ist ein bereits erfolgter Schreibvorgang auf die Plugin-Option. Anders als beim admin_init-Aufhänger der Migration in upgrade.php gibt es hier keinen anonym erreichbaren Pfad — wer die Option schreiben kann, hat die Site ohnehin in der Hand.

creationell_captcha_store_settings()

Der eine Schreibweg des Plugins auf `creationell_captcha_settings`.

creationell_captcha_store_settings(array<string, mixed> $clean) : void

Warum es ihn gibt (Nachlese N6, Befund 4): update_option() feuert update_option_{$option} NUR, wenn sich der gespeicherte Wert wirklich ändert (wp-includes/option.php vergleicht alt/neu und bricht sonst ohne DB-Schreibvorgang und ohne Hook ab). Seit E3b hängt die Anlage der Ereignis-Tabelle ausschliesslich an diesen Hooks — ein Schreibvorgang ohne Wertänderung ist damit ein Erfolg ohne Wirkung:

wp creacaptcha settings set analytics_event_log 1   # steht schon auf 1
wp creacaptcha blocklist add 203.0.113.9            # steht schon drin

meldeten Erfolg, während eine von Hand gelöschte Tabelle (DB-Restore, Migration) weg blieb und jedes Ereignis still verworfen wurde. Strang N2 hatte das für Command::enable() einzeln kompensiert; der zweite und dritte CLI-Weg auf denselben Schlüssel hatten die Kompensation nicht. Statt sie an jeder Stelle zu wiederholen, steht sie jetzt EINMAL hier, und alle Plugin-eigenen Schreibwege gehen hindurch.

Nachgerufen wird nur, wenn update_option() FALSE liefert — also genau dann, wenn der Hook nicht gefeuert hat. ensure_table() ist zwar idempotent, aber nicht kostenlos (dbDelta liest das Schema), und ein zweiter Durchlauf bei jedem echten Speichervorgang wäre reine Wiederholung. Der FALSE-Zweig deckt beide Ursachen ab: unveränderter Wert und fehlgeschlagener Schreibvorgang.

Parameters
$clean : array<string, mixed>

Bereits sanitisierter Wertesatz.

Tags
since
1.1.0

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

Liefert das Label eines Einstellungsfeldes (Fallback: der Schlüssel selbst).

creationell_captcha_field_label(string $key) : string
Parameters
$key : string

Feldschlüssel.

Return values
string

creationell_captcha_field_spec()

Request-lokal gehaltene Feldspezifikation für die beiden Label-Helfer.

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

W2-8: Beide hielten je einen wortgleichen static $spec-Block und damit zwei unabhängige Kopien der ~75-Felder-Spezifikation im Speicher. Eine gemeinsame Zugriffsfunktion genügt — und sie macht zugleich sichtbar, dass beide denselben Stand meinen.

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

creationell_captcha_field_option_label()

Liefert das Options-Label eines `select`-Feldes (Fallback: der Rohwert).

creationell_captcha_field_option_label(string $key, string $value) : string
Parameters
$key : string

Feldschlüssel.

$value : string

Optionswert.

Return values
string 

        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results