Developer Reference

wp_authenticate_user

Main authentication filter. Applies delays and lockouts to login attempts. Parameters: $user (WP_User|WP_Error), $password. Returns WP_Error if locked out, otherwise applies sleep() delay on failure and returns $user.

rest_authentication_errors

REST API authentication protection. Applies delays and lockout to failed REST API authentication when wldelay_rest_enabled is on. Returns a 403 WP_Error if the IP is locked out. Respects the IP whitelist and skips application-password attempts (handled separately). Since v2.1.2.

authenticate

Application-password authentication protection. Applies delays and lockout to failed Basic Auth attempts when wldelay_application_password_enabled is on. Detects app-password attempts via PHP_AUTH_USER/PHP_AUTH_PW server headers. Parameters: $user, $username, $password. Since v2.1.2.

authenticate

Blocks XML-RPC authentication when the “block XML-RPC” setting is enabled. Parameters: $user, $username, $password. Returns WP_Error('wldelay_xmlrpc_blocked') for XML-RPC requests.

wldelay_2fa_providers

Customize the list of recognized 2FA plugins for the settings-page health check. Receives an associative array of slug => [ plugin_basename, … ]. Return the modified array to add or remove providers. The default map includes two-factor, wp-2fa, mini-orange, and google-authenticator. Since v2.1.4.

wldelay_2fa_coverage_checkers

Register provider-specific callbacks that report privileged-user 2FA coverage for the settings-page notice. Receives a map of provider_slug => callable (the built-in entry covers the two-factor plugin). Each callback returns an array with keys supported, privileged_total, protected, unprotected, and unknown.

wldelay_normalize_username

Customize how usernames are normalized for failure tracking and lockout identity. Receives the normalized username and the original input. Return your own normalized value to support LDAP, email-as-login, or SSO backends where the default lowercase/sanitize behavior is not enough. Since v2.3.0.

wldelay_persistence_store

Swap the lockout persistence backend. Receives null; return a WLDelay_Persistence implementation to replace the default DB-backed store (for example a Redis or external store) without touching call sites. Falls back to WLDelay_DB_Persistence when the filter returns anything else.

wldelay_login_help_url

Set the “Need help getting in?” link shown in the login-page lockout feedback block. Defaults to the site’s lost-password URL (respecting any custom-login-slug rewrite); point it at a support or docs page instead. Returned value is escaped at output.

wldelay_fail2ban_allowed_log_dirs

Extend the set of directories a custom fail2ban log path may live in. By default only the plugin-owned protected directory is allowed; add server-protected directories here. Web-server protection files (.htaccess, index.html, index.php) are written to every allowed directory. A custom path outside the allowed set disables logging rather than writing elsewhere.

wldelay_fail2ban_max_log_bytes

Control the size at which the fail2ban log is rotated to a single .log.1 backup. Defaults to 5 MB. Return 0 to disable in-plugin rotation and rely on system logrotate instead. Since v2.3.4.

wldelay_botnet_ip_threshold

Number of distinct source IPs targeting one username that triggers a distributed-attack alert. The stored option is clamped to [2, 100] before the filter runs, and the result is re-floored at 2 so a filter cannot drop below the minimum. Default 5. Since v2.5.0.

wldelay_botnet_window

Sliding detection window, in seconds. The stored minutes option is clamped to [5, 60] and converted to seconds before the filter; the result is floored at MINUTE_IN_SECONDS. Default 900 (15 minutes). Since v2.5.0.

wldelay_botnet_alert_cooldown

Per-username cooldown, in seconds, that suppresses repeat distributed-attack alerts after one fires. Default HOUR_IN_SECONDS. Since v2.5.0.

wldelay_cloudflare_ip_ranges

The list of Cloudflare CIDR ranges used to validate the CF-Connecting-IP header. The header is honored only when REMOTE_ADDR falls inside one of these ranges, so it cannot be spoofed. Return your own array to extend or replace the built-in IPv4/IPv6 ranges. Since v2.4.0.

wldelay_send_custom_login_email

Whether to email the new login URL to the site admin when the Custom Login URL feature is enabled or its slug changes. Default true; return false (e.g. __return_false) to suppress the recovery email. Since v2.4.0.

wldelay_help_base_url

Base URL for the “Learn more” documentation links on each settings card. Defaults to https://damoiseau.xyz/docs/login-delay-shield/user-guide/. Return an empty string to hide the links, or point them at your own mirror. Since v2.5.0.

wldelay_export_login_log_should_exit

Controls whether the CSV export handler calls exit() after streaming. Default true. Set to false in test environments. Since v2.1.2.

plugin_action_links_{basename}

Adds a “Settings” link to the plugin’s entry on the Plugins page.

wp_login_failed

Hooked to log failed login attempts to the database. Parameters: $username. Records the IP address, username, timestamp, and source (wp-login, xmlrpc, rest, application-password, or password-reset).

wldelay_cleanup_logs

Custom cron hook that runs daily. Deletes log entries older than the configured retention period. Processes in batches of 1,000 rows.

wp_dashboard_setup

Registers the “Recent Failed Login Attempts” dashboard widget.

admin_post_wldelay_unlock_current_ip

Handles the “Unlock Current IP” button on the settings page. Removes the lockout and failure counters for the requesting admin’s IP address. Nonce-protected and requires manage_options capability.

admin_post_wldelay_export_login_log

Handles CSV export of the failed login log. Streams results in 1,000-row batches with formula-injection protection. Reads optional filters from $_GET (source, IP, username, date range). Nonce-protected and requires manage_options capability. Since v2.1.2.

admin_post_wldelay_recovery_generate

Mints a new Emergency Recovery token, stores its hash, emails the URL to the site admin, and sets the one-time reveal. Nonce-protected, requires manage_options. Since v2.6.0.

admin_post_wldelay_recovery_download

Streams the once-revealed recovery URL as a .txt download. Nonce-protected, requires manage_options; only works inside the reveal window. Since v2.6.0.

admin_post_wldelay_recovery_confirm / admin_post_nopriv_wldelay_recovery_confirm

Handles the confirm POST from the recovery landing page. Re-validates the token and nonce, then clears the caller’s own IP lockout (it never logs the user in). Registered for both authenticated and unauthenticated callers so a locked-out admin can use it. Since v2.6.0.

wldelay_event_{event}

Per-event hook fired for each plugin event (e.g. wldelay_event_cron_tick). Receives the event payload array. Subscribe with wldelay_on_event(), or hook the generic wldelay_event action (which receives $event_name, $payload) to observe every event as an audit/SIEM firehose.

wldelay_persistence_write_failed

Fires when a lockout could not be written to the durable store. Parameters: $ip, $type (login or password-reset). The lockout falls back to transient-only state until the store recovers.

wldelay_audit_write_failed

Fires when an audit-log row could not be written. Parameters: $action (the action key whose row was lost), $error (DB error string).