WP Ghost Plugin Hooks Reference for Developers

Table of Contents

WP Ghost exposes over 80 filters and actions that let developers customize security behavior, extend features, and integrate with other systems. All hooks follow the hmwp_* naming convention. This reference covers the most useful hooks organized by category, with descriptions of what each hook does, when to use it, and what result to expect. For hooks with dedicated tutorials, links are provided. Add all hook code to your child theme’s functions.php or a custom plugin.

Reading plugin settings in callbacks. Use HMWP_Classes_Tools::getOption('hmwp_option_name') to read any WP Ghost setting inside your hook callbacks. All hooks are available from the plugins_loaded action onward.

Authentication and Login Hooks

These hooks fire during WP Ghost’s custom login and logout flows. Use them to audit logins, customize redirects, enforce SSO, or trigger third-party integrations.

hmwp_user_auth_success (action) fires immediately after a user is authenticated through 2FA, a temporary link, or a magic link. Receives the WP_User object and a method string ('two_factor_login', 'temporary_login', or 'magic_link_login'). Use it to log every alternative-auth login to a custom audit table or trigger a third-party analytics event.

hmwp_login_init (action) fires during the custom login page initialization, before any output. Use it to enforce SSO redirects, pre-populate fields, or run logic that must happen at login time. See Redirect Logged Users to Dashboard for a practical example.

hmwp_wp_logout (action) fires when the plugin processes a logout, after the WordPress session is destroyed. Use it to clear custom session cookies or log logout events.

hmwp_url_login_redirect (filter) filters the URL a user is sent to after a successful login through WP Ghost’s custom login flow. Return a URL string to override the default admin dashboard redirect. For example, send editors to the posts list instead of the dashboard.

hmwp_url_logout_redirect (filter) filters the URL a user is sent to after logout. Return false (default) to use WordPress’s own redirect logic, or return a URL string to override it.

Two-Factor Authentication (2FA) Hooks

These hooks customize 2FA behavior: token expiration, email content, rate limiting, TOTP configuration, and backup codes.

hmwp_token_ttl (filter) controls how long an emailed 2FA token remains valid, in seconds. Default: 900 (15 minutes). Receives the TTL and user ID, so you can set shorter windows for administrators and longer ones for regular users.

hmwp_email_subject (filter) and hmwp_email_message (filter) customize the 2FA email sent to users. The subject filter receives the subject string and user ID. The message filter receives the message body (with the token already inserted), the raw token string, and the user ID. Use these to brand the email or add instructions.

hmwp_attempt_limit_reached (filter) controls whether a 2FA login attempt should be rate-limited. Receives a boolean and the WP_User object. Return false to skip rate-limiting for trusted IP ranges.

hmwp_totp_issuer (filter) and hmwp_totp_title (filter) customize the authenticator app display. The issuer appears as the account label in apps like Google Authenticator. The title sets the account name. Both receive the default string and user ID.

hmwp_totp_time_step_allowance (filter) sets how many 30-second TOTP time steps are accepted on either side of the current step. Default: 1 (accepts codes from the previous, current, and next 30-second window). Increase to 2 to compensate for clock drift on older devices.

hmwp_codes_number (filter) controls how many backup recovery codes are generated per user. Default: 8. Increase for users who frequently need recovery codes.

Firewall and Threat Detection Hooks

These hooks let you respond to firewall events, customize threat handling, manage IP whitelists and banlists, and modify the block page.

hmwp_threat_detected (action) is the central threat hook. Fires every time the firewall identifies a threat. Receives an array with at minimum a 'code' key (threat code string). Use it to send real-time Slack alerts, trigger SIEM integrations, or push to external logging services.

hmwp_firewall_block (action) fires when the firewall actively blocks a request (as opposed to just detecting it). Use it for actions that should only happen on actual blocks, not detections.

hmwp_process_firewall (filter) controls whether the firewall engine runs for the current request. Return false to disable the firewall for specific contexts (API endpoints, trusted services). hmwp_process_threats (filter) similarly controls whether threat detection rules execute.

hmwp_whitelisted_ips (filter) adds IPs or CIDR ranges to the firewall whitelist. Whitelisted IPs bypass all firewall checks. Use it to programmatically trust office IPs, monitoring services, or payment gateways.

hmwp_banlist_ips (filter) adds IPs to the permanent block list. Use it to pull IPs from an external threat intelligence feed or a shared blocklist.

hmwp_firewall_block_template (filter) filters the HTML template shown to blocked visitors. hmwp_404_template (filter) filters the 404 page template used when WP Ghost returns a 404 for hidden paths. Use these to brand the block page or add custom messaging.

hmwp_threats_threat_patterns (filter) filters the regex patterns used by the firewall to identify threats. Add custom patterns to detect application-specific attack signatures.

Brute Force Protection Hooks

hmwp_preauth_check (filter) controls whether the pre-authentication brute force check runs. Return false to skip it for trusted API consumers or REST API calls using application passwords.

hmwp_brute_max_timeout (filter) filters the brute force lockout duration in seconds. The default comes from the WP Ghost setting. Override it to extend lockouts (for example, 2 hours instead of the default) or shorten them for specific contexts.

URL Rewriting and Path Security Hooks

These are the core hooks that control WP Ghost’s path security engine. They let you disable rewriting for specific contexts, modify the rewrite rules, filter the HTML output buffer, and customize path handling. For a practical tutorial showing how to disable these by user role, see Disable WP Ghost for User Roles.

hmwp_process_init (filter) is the master switch for the path rewriting engine. Return false to disable WP Ghost’s rewriting entirely for the current request. Use it to skip rewriting for WP-CLI commands, imports, or cron jobs. See Disable WP Ghost on Specific Pages for a practical example.

hmwp_process_hide_disable (filter) controls whether the path renaming feature (wp-admin, wp-content, etc.) executes. hmwp_process_hide_urls (filter) controls whether URL hiding in HTML output runs. hmwp_process_find_replace (filter) controls whether the find-and-replace pass runs on the output buffer. These three hooks give you granular control over which parts of the rewriting pipeline execute.

hmwp_start_buffer (filter) controls whether the PHP output buffer starts at all. Return false to skip buffering for JSON API responses or other non-HTML output. hmwp_process_buffer (filter) controls whether the buffered HTML is processed for replacements. Use this to skip rewriting on specific page types without stopping the buffer entirely.

hmwp_buffer (filter) is the lowest-level text hook. It filters the complete HTML output just before it’s sent to the browser, after all WP Ghost rewrites have been applied. Use it for final-pass text replacements.

hmwp_rewrites (filter) filters the rewrite rules array before they’re applied. Each rule has 'from' (regex pattern) and 'to' (target) keys. hmwp_umrewrites (filter) filters the “unmask” rules that map custom paths back to real WordPress paths internally.

hmwp_replace_before (filter) filters the find-and-replace pairs used for URL rewriting. Keys are strings to find, values are replacements. Use it to add custom path replacements for vendor directories or third-party assets.

hmwp_emulate_cms (filter) filters the generator meta tag content. Return a string like 'Drupal 9' to emit a fake CMS identifier. See Simulate Drupal or Joomla CMS for the full guide.

hmwp_hide_commonfiles_files (filter) filters the list of common files (readme.html, license.txt, etc.) that WP Ghost blocks direct access to. Add custom files to the blocked list. See Add Files to Hide Common Files for the tutorial.

hmwp_option_[key] (dynamic filter) filters any individual WP Ghost option at read time. Replace [key] with the full option name (for example, hmwp_option_hmwp_login_url to override the login URL). See Customize Right Click Disable for an example using hmwp_option_hmwp_disable_click.

hmwp_flushed_rewrites (action) fires after WP Ghost flushes rewrite rules. Use it to purge Varnish, a CDN, or a proxy cache after path changes.

Temporary Login Hooks

These hooks customize the Temporary Login feature: URL generation, access restrictions, and settings.

hmwp_templogin_link (filter) filters the temporary login URL before it’s displayed or emailed. Receives the URL string and the temporary user’s ID. Use it for auditing or adding tracking parameters.

hmwp_templogin_restricted_pages (filter) filters the list of admin page slugs that temporary login users cannot access. Add your custom settings pages to prevent temporary users from viewing them.

hmwp_templogin_restricted_actions (filter) filters the list of WordPress admin actions forbidden for temporary users. Block sensitive actions like 'export' or 'delete-site' to limit what temporary users can do.

Magic Login Hooks

These hooks customize the Magic Link (passwordless login) feature.

hmwp_unique_login_link (filter) filters the magic login URL before it’s sent. Receives the URL and user ID. Use it to append UTM parameters for analytics tracking.

hmwp_unique_login_subject (filter) and hmwp_unique_login_message (filter) customize the magic login email. The subject filter receives the subject and user ID. The message filter receives the body, the magic URL, and the user ID. Use them to brand the email or add custom instructions.

Settings and Configuration Hooks

These hooks fire when WP Ghost settings are saved, and let you modify configuration values and validation.

Settings-saved actions fire after each major settings tab is saved. Use them to react to configuration changes without polling: hmwp_settings_saved (Change Paths), hmwp_tweakssettings_saved (Tweaks), hmwp_mappsettings_saved (Mapping), hmwp_firewall_saved (Firewall), hmwp_advsettings_saved (Advanced), hmwp_logsettings_saved (Logs), and hmwp_confirmed_settings (initial setup confirmation).

hmwp_apply_permalink_changes (action) fires after permalink changes have been written. Use it to purge full-page caches (WP Rocket, Varnish, etc.) after path changes.

hmwp_text_mapping_before_save (filter) and hmwp_url_mapping_before_save (filter) let you modify Text Mapping and URL Mapping entries before they’re saved to the database. Use them to validate, sanitize, or inject additional mapping rules.

hmwp_validate_keys (filter) and hmwp_invalid_names (filter) control path validation. hmwp_validate_keys filters the list of setting keys that require validation. hmwp_invalid_names filters path names that are forbidden (to prevent breaking WordPress by using reserved names).

hmwp_rules_whitelisted_cookies (filter) and hmwp_rules_whitelisted_ips (filter) add cookies and IPs to the whitelist at the rules-generation level. This affects both runtime checks and server config file generation (.htaccess/nginx).

Logging and Events Hooks

These hooks customize the Events Log and Threats Log: what gets logged, how it’s stored, and how it’s purged.

hmwp_allow_actions (filter) filters the list of action names the Events Log records. Add custom action names to log events from your own plugins or integrations.

hmwp_allow_keys (filter) filters the list of data keys the Events Log captures per event (for example, which POST fields to record). Add custom field names to capture additional data.

hmwp_threats_log_purge_batch (filter) controls how many rows are deleted per batch when purging the Threats Log. Default: 5000. Reduce on resource-constrained servers to prevent timeouts. hmwp_threats_log_purge_max_seconds (filter) controls the maximum wall-clock time (in seconds) a single purge run takes. Default: 10.

Admin UI Extension Hooks

WP Ghost exposes form boundary hooks on every major settings page, letting you inject custom HTML, fields, or notices into the WP Ghost admin interface without modifying plugin templates.

Each settings page has a _form_beginning and _form_end action hook inside its <form> element: hmwp_change_paths_form_beginning/_end, hmwp_brute_force_form_beginning/_end, hmwp_firewall_form_beginning/_end, hmwp_mapping_form_beginning/_end, hmwp_tweaks_form_beginning/_end, hmwp_two_factor_form_beginning/_end, hmwp_event_log_form_beginning/_end, hmwp_temporary_login_form_beginning/_end, hmwp_advanced_form_beginning/_end, and hmwp_security_check_beginning/_end.

hmwp_getview (filter) filters the rendered HTML of any admin view or block before it’s displayed. Receives the HTML string and the block/view name. Use it to wrap specific pages in custom containers or inject additional content.

hmwp_login_css (filter) filters the inline CSS injected on the WordPress login page when WP Ghost’s login page styling is enabled. Use it to add custom branding styles. See Change or Remove Login Logo Link for a related customization.

hmwp_menu (filter) and hmwp_submenu (filter) let you modify the WP Ghost admin menu structure. See Hide and Show WP Ghost in the Menu for controlling menu visibility.

Frequently Asked Questions

Where should I add hook code?

Add hook callbacks to your child theme’s functions.php file or a custom plugin (a simple plugin with a header comment is fine). Don’t add code to WP Ghost’s files directly as updates will overwrite your changes. Don’t use the parent theme’s functions.php as theme updates will remove your code.

Can I control the order hooks fire?

Yes. All WP Ghost hooks support WordPress’s standard priority system. Use the third parameter of add_filter() or add_action() to set priority (default: 10, lower numbers fire earlier). For example, add_filter('hmwp_buffer', 'my_callback', 20) runs after WP Ghost’s own processing at priority 10.

Is it safe to return false on process filters?

Returning false on process filters (hmwp_process_init, hmwp_process_buffer, hmwp_process_firewall, etc.) disables that specific security feature for the current request. Be precise about your conditions: disable by IP, user role, or page type rather than globally. Disabling path rewriting or the firewall for all requests removes protection entirely.

How do I override a specific WP Ghost setting?

Use the dynamic hmwp_option_[key] filter. For example, to force the login URL regardless of the saved setting: add_filter('hmwp_option_hmwp_login_url', function() { return 'my-login'; });. This overrides the value at read time without changing the database.

Does WP Ghost modify WordPress core files?

No. WP Ghost uses server rewrite rules and WordPress hooks for all security features. The developer hooks documented on this page use WordPress’s standard add_filter() and add_action() system. No core files are modified.

Tutorials with practical hook implementations:

Tagged: