Skip to content

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', '>=' ).

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_DEBUG on, the error is written to the debug log.
  • Session data passed to hooks never contains the secret session token or the emergency exit key.

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 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.

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.

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.

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.

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.

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 );

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

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>';
} );

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|string

Return '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().

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.

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 ): int

The 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.

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.

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.

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.

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).

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>';
} );

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

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.

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(): array|null

The current step (see Step data), or null when this browser has no session of the current user.

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( string $action ): string

A 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.