Hooks reference
Culprit Finder offers a small set of actions, filters and functions so add-ons can extend it without touching its code. All hook and function names start with culprit_finder_. Everything marked “since 0.2.0” needs Culprit Finder 0.2.0 or newer; check with function_exists( 'culprit_finder_submit_answer' ) or version_compare( CULPRIT_FINDER_VERSION, '0.2.0', '>=' ).
Safety rules
Section titled “Safety rules”Every callback runs through a guard, so an add-on can’t break the site:
- While your callback runs, any attempt to change the list of active plugins (
update_option( 'active_plugins', … )) is silently ignored. Culprit Finder never changes your real plugin settings, and neither can a hook. - If your callback throws an error, it is skipped. For a filter, the original value is used instead. With
WP_DEBUGon, the error is written to the debug log. - Session data passed to hooks never contains the secret session token or the emergency exit key.
Session data
Section titled “Session data”Several hooks receive $session, an array with these keys:
| Key | Type | Meaning |
|---|---|---|
user_id |
int | The administrator running the session. |
created_at |
int | When the session started (Unix time). |
expires_at |
int | When it ends if nobody answers (Unix time). Never later than ends_at. |
ends_at |
int | When it ends at the latest, answers or not (Unix time). Since 0.2.0; missing for sessions started by 0.1.0. |
self |
string | Culprit Finder’s own plugin file, always on. |
snapshot |
string[] | The active plugins when the session started. |
pinned |
string[] | Plugins the user chose to keep on. |
deps |
array | Plugin → plugins it requires (within the snapshot). |
answers |
bool[] | Answers so far; true means “the problem is still there”. |
fixed |
string[] | Plugins on in every step (kept on, their requirements, Culprit Finder). |
enabled_now |
string[] | Plugins on in the current step. |
problem_url |
string | The broken page’s address, or an empty string. |
always_on |
string[] | Add-ons kept on in every step through culprit_finder_always_on. Since 0.2.0; missing for sessions started by 0.1.0. |
Plugins are identified by their file path relative to the plugins folder, for example acme-invoices/acme-invoices.php.
Step data
Section titled “Step data”$step is an array:
| Key | Type | Meaning |
|---|---|---|
status |
string | asking or done. |
phase |
string | baseline, find_first, solo, find_partner, verify or done. |
question |
int | The number of the current question (1-based). |
estimated_total |
int | About how many answers the search will take. |
enabled |
string[] | Plugins on in this step. |
disabled |
string[] | Plugins off in this step (for this browser only). |
result |
array|null | When done: type, culprits, kept_on. |
answers_used |
int | Answers the search has used. |
Result types: SINGLE, PAIR, COMPLEX, NOT_PLUGIN, NOTHING_TO_TEST, INCONCLUSIVE.
Actions
Section titled “Actions”culprit_finder_session_started
Section titled “culprit_finder_session_started”Fires after a troubleshooting session starts (from the admin page or WP-CLI).
do_action( 'culprit_finder_session_started', array $session, array $step );$step is the first question.
culprit_finder_step_changed
Section titled “culprit_finder_step_changed”Fires after an answer or an undo changes the current step.
do_action( 'culprit_finder_step_changed', array $step, array $session, string $cause );$cause is answer or undo. When an answer finishes the search, culprit_finder_result_found fires first, then this action with a done step.
culprit_finder_result_found
Section titled “culprit_finder_result_found”Fires when a search finishes and its result is saved.
do_action( 'culprit_finder_result_found', array $result, array $session );$result is the saved result: id, version, result (type, culprits, kept_on), answers, tested, finished_at, plugins (name, version, author, website and requirements of the plugins involved) and env (WordPress and PHP versions, theme, multisite). It contains no user data.
Since 0.3.1 it also has replay: what’s needed to repeat the search step by step (snapshot, self, kept, deps, answers as booleans, and names, the name and version of every plugin tested). Results saved by older versions don’t have it.
culprit_finder_session_ended
Section titled “culprit_finder_session_ended”Fires when a session ends.
do_action( 'culprit_finder_session_ended', string $reason, array $session );$reason |
When |
|---|---|
exit |
The user pressed Exit or Done, or ran wp culprit-finder exit. |
expired |
Nobody answered for an hour, or the session reached its maximum length (three hours unless lowered with culprit_finder_max_session_length); noticed on the next request from the troubleshooting browser or the next admin request. |
replaced |
A new session started while one was running. |
recovery |
Someone opened the emergency exit link. |
deactivated |
Culprit Finder was deactivated. |
Filters
Section titled “Filters”culprit_finder_report_sections
Section titled “culprit_finder_report_sections”Change the support report. Sections are joined with a blank line, in array order.
apply_filters( 'culprit_finder_report_sections', array $sections, array $result ): array$sections starts as [ 'result' => …, 'environment' => …, 'steps' => …, 'footer' => … ], each a block of plain-text lines. Add, change, reorder or remove sections. Sections you add at the end come after footer, as before.
steps is new in 0.3.1: one line per answer, in order, with the step’s phase (Baseline, Find first, Pair search, Confirm), the plugins that were off (names and versions) and the answer. It is missing for results saved by older versions, and for results with no answers (nothing to test). The report is pasted into public forums, so never add site addresses, user names or email addresses.
add_filter( 'culprit_finder_report_sections', function ( $sections, $result ) { $sections['acme'] = 'Acme Hosting: PHP workers 4'; return $sections;}, 10, 2 );culprit_finder_admin_tabs
Section titled “culprit_finder_admin_tabs”Add a tab to the Culprit Finder page.
apply_filters( 'culprit_finder_admin_tabs', array $tabs ): array$tabs maps tab ids to labels. The three built-in tabs (troubleshoot, results, help) always come first and can’t be renamed or removed. Ids are passed through sanitize_key().
culprit_finder_render_tab_{$id}
Section titled “culprit_finder_render_tab_{$id}”Render the content of your tab.
do_action( "culprit_finder_render_tab_{$id}", array|null $session );$session is the running session if this browser owns it, otherwise null. Escape everything you print.
add_filter( 'culprit_finder_admin_tabs', function ( $tabs ) { $tabs['acme'] = __( 'Acme', 'acme' ); return $tabs;} );add_action( 'culprit_finder_render_tab_acme', function ( $session ) { echo '<p>' . esc_html__( 'Hello from Acme.', 'acme' ) . '</p>';} );culprit_finder_auto_answer
Section titled “culprit_finder_auto_answer”Answer a step automatically, for example after checking the broken page yourself.
apply_filters( 'culprit_finder_auto_answer', null $answer, array $step, array $session ): null|stringReturn 'yes' (the problem is still there), 'no' (it’s gone), or null to let the user answer. Any other value is ignored.
The filter only runs when the administrator who owns the session opens the Troubleshoot tab in that same browser. It never runs for visitors, other users or WP-CLI. Automatic answers count like normal ones, so Undo still works. Culprit Finder asks again after each automatic answer, until you return null or the search finishes. Since 0.2.0, the browser’s session cookie gets the new expiry after automatic answers, exactly like after a click.
To answer from your own request instead (a REST route, an AJAX call), use culprit_finder_submit_answer().
culprit_finder_always_on
Section titled “culprit_finder_always_on”Since 0.2.0. Keep your add-on on in every step and in safe mode, so its screens, REST routes and hooks keep working during troubleshooting. The user doesn’t have to tick it.
apply_filters( 'culprit_finder_always_on', string[] $basenames, string[] $snapshot ): string[]$basenames starts empty; add your own plugin file. $snapshot is the list of active plugins. Runs once when a session starts, and when the setup screen is shown.
Culprit Finder only accepts a plugin that is active and declares Requires Plugins: culprit-finder in its header. Anything else is ignored, so a plugin can’t hide from the search by asking. Plugins your add-on requires stay on too.
Add-ons kept on this way are never suspects, so they are always visible: the setup screen lists them as “Always on · Culprit Finder add-on”, each step’s plugin list marks them, and the result and the support report list them as kept-on add-ons. They are stored in the session as always_on and in the result as always_on.
/* * Plugin Name: Acme Helper * Requires Plugins: culprit-finder */add_filter( 'culprit_finder_always_on', function ( $basenames ) { $basenames[] = plugin_basename( __FILE__ ); return $basenames;} );Your filter must be registered when the session starts, so the add-on has to be active and loaded then.
culprit_finder_max_session_length
Section titled “culprit_finder_max_session_length”Since 0.2.0. Every session ends by itself after three hours at most, even when answers keep coming (from the user or from an add-on). Lower that limit:
apply_filters( 'culprit_finder_max_session_length', int $seconds ): intThe value is stored in the session as ends_at when it starts. Values above 10800 (three hours) are ignored, values below 60 become 60, and anything that isn’t a positive number keeps the default. The idle timeout (an hour without answers) still applies on top.
culprit_finder_problem_url_required
Section titled “culprit_finder_problem_url_required”Since 0.2.0. Make “Where do you see the problem?” required.
apply_filters( 'culprit_finder_problem_url_required', bool $required, array|null $input ): bool$input is null while the setup screen renders (return true to show the field as required) and the submitted input when the user presses Start (see culprit_finder_before_start). Only exactly true counts. When it is true and no address of this site was entered, nothing starts and the setup screen asks for it.
culprit_finder_before_start
Section titled “culprit_finder_before_start”Since 0.2.0. Check the setup form before a session starts, and stop it with a message.
apply_filters( 'culprit_finder_before_start', true|WP_Error $ok, array $input ): true|WP_Error$input key |
Type | Meaning |
|---|---|---|
problem_url |
string | The broken page’s address (same site only), or an empty string. |
pinned |
string[] | Plugins the user ticked (not yet validated). |
addon |
array | Your fields from culprit_finder_setup_fields, sanitized. |
Return a WP_Error to stop: its message is shown at the top of the setup screen as plain text, and the form keeps what the user entered, including the emergency exit link they already saved. Anything else lets the session start. Runs for the setup form and Run again, not for WP-CLI.
culprit_finder_admin_bar_label
Section titled “culprit_finder_admin_bar_label”Since 0.2.0. Change the text of the purple toolbar item during a session.
apply_filters( 'culprit_finder_admin_bar_label', string $label, array $step, array $session ): string$label is for example “Culprit Finder · Step 2 of ~7 · still broken?”. Return a non-empty string; it is escaped for you. The Yes, No, Undo and Exit items stay.
Screen hooks
Section titled “Screen hooks”Since 0.2.0. Print your own markup on Culprit Finder’s screens. Escape everything you print. Without callbacks, the screens are unchanged (the setup screen’s numbered layout is the same with or without add-ons; only the numbering changes).
culprit_finder_setup_fields
Section titled “culprit_finder_setup_fields”Your own section inside the setup form, right after “Where do you see the problem?”.
do_action( 'culprit_finder_setup_fields', array $values );Section row (since 0.3.0). The setup screen shows numbered sections. Culprit Finder buffers what your callback prints and, if it shows anything, puts it in its own numbered row right after section 1, so your section is number 2 and “Keep any plugins on?” moves to 3. Print your section’s heading and content; Culprit Finder supplies the row, the number circle and the padding. The recommended markup is one <fieldset class="cf-field"> with a <legend> as the heading: inside a row, .cf-field has no padding or border of its own and its legend is styled like the other section headings, so markup written for 0.2.0 fits as is. Don’t print your own outer padding, border or number. If several add-ons print, they share that one row. The main card (.cf-setup__main) is a CSS size container (container-type: inline-size), so your styles can adapt to its width with @container queries (it is about 340px wide at a 1024px window with the sidebar, and the full width below 961px). Output that shows nothing (only whitespace, comments, <script>, <style>, <template> or <input type="hidden">) gets no row; it is still printed inside the form, so hidden fields are submitted.
Name your fields culprit_finder_addon[your-id][...]. They arrive in culprit_finder_before_start as $input['addon']['your-id']: keys are passed through sanitize_key(), values through sanitize_textarea_field(), at most three levels deep. $values holds the same array after a refused start (so you can fill your fields in again), otherwise an empty array.
add_action( 'culprit_finder_setup_fields', function ( $values ) { $note = isset( $values['acme']['note'] ) ? $values['acme']['note'] : ''; echo '<fieldset class="cf-field"><legend>' . esc_html__( 'Acme note', 'acme' ) . '</legend>'; echo '<input type="text" name="culprit_finder_addon[acme][note]" value="' . esc_attr( $note ) . '"></fieldset>';} );culprit_finder_step_panel
Section titled “culprit_finder_step_panel”The question area of the running step, for the browser that owns the session.
do_action( 'culprit_finder_step_panel', array $step, array $session );If your callbacks print anything, it replaces the question, the Open link, the Yes / No buttons and Undo. The progress bar, “Step X of about N”, Stop and exit and the list of plugins on in this step always stay. Print nothing to keep the normal question. To offer the normal answers inside your panel, link to culprit_finder_action_url().
culprit_finder_result_actions
Section titled “culprit_finder_result_actions”Buttons next to Copy for forum and the downloads on a saved result.
do_action( 'culprit_finder_result_actions', array $result, array|null $session );$result is the saved result (as in culprit_finder_result_found, without user data). $session is the running session when this browser owns the session that produced the result, otherwise null.
Functions
Section titled “Functions”Since 0.2.0. These work only for the administrator who owns the running session, in the browser that holds the session cookie, and never in WP-CLI (use wp culprit-finder there). Check your own nonce and permissions before changing anything, as in any request that changes state.
culprit_finder_current_step()
Section titled “culprit_finder_current_step()”culprit_finder_current_step(): array|nullThe current step (see Step data), or null when this browser has no session of the current user.
culprit_finder_submit_answer()
Section titled “culprit_finder_submit_answer()”Answer the current question from your own request, for example after checking the broken page yourself.
culprit_finder_submit_answer( string $answer, int $question ): array|WP_Error$answer is 'yes' (the problem is still there) or 'no'. $question must be the question of the step you are answering; if the step has moved on meanwhile, nothing is recorded. The answer counts like a click: Undo works, culprit_finder_step_changed (and culprit_finder_result_found at the end) fire, and the browser’s session cookie gets the new expiry. Returns the new step.
| Error code | When |
|---|---|
culprit_finder_not_owner |
No session of the current user in this browser, logged out, another user, or WP-CLI. |
culprit_finder_invalid_answer |
$answer isn’t exactly 'yes' or 'no'. |
culprit_finder_stale_question |
$question isn’t the current question, or the search has finished. |
register_rest_route( 'acme/v1', '/answer', array( 'methods' => 'POST', 'permission_callback' => function () { return current_user_can( 'activate_plugins' ); }, 'callback' => function ( WP_REST_Request $request ) { return culprit_finder_submit_answer( $request['answer'], (int) $request['question'] ); },) );culprit_finder_action_url()
Section titled “culprit_finder_action_url()”culprit_finder_action_url( string $action ): stringA link that does what the built-in buttons do, for 'yes', 'no' or 'undo', and then returns to the control panel. Returns an empty string when this browser has no session of the current user.
WordPress is a trademark of the WordPress Foundation. Culprit Finder is not affiliated with or endorsed by the WordPress Foundation.