Toggle an add-on’s verbose logging or extra diagnostics in lock-step with Benecaster Support Mode

Premium Beginner Since v1.0.0

Benecaster’s Support Mode raises its own log verbosity for the next 7 days and auto-disables on a one-shot WP-Cron event. Add-ons that have their own logger or diagnostic recorder should mirror that lifecycle so a customer who enables Support Mode also gets full add-on context in the bug report. $reason in the disabled action is 'manual' or 'auto'. Read the current state via SupportMode::is_active() or get_option( 'benecaster_support_mode_enabled' ).

When to Use This

When your add-on has its own logger, breadcrumb buffer, or diagnostic recorder. If you gate verbose logging on your own settings option, hooking the Support Mode lifecycle means a customer enabling Support Mode in Benecaster automatically gets full add-on context in the resulting snapshot — without needing to configure anything in your add-on separately.

Implementation

Hook benecaster_support_mode_enabled to turn your verbose logging on and benecaster_support_mode_disabled to turn it off. The enable hook receives the timestamp at which Benecaster will auto-disable, so you can schedule a parallel cleanup cron and guarantee your add-on never logs past the same cutoff even if Benecaster’s own cron is rescheduled. The disable hook receives a reason string.

Then gate your logging function on whatever option those callbacks set, and route messages through benecaster_debug_log with an add-on prefix so they land in the same table Benecaster reads for the snapshot.

Reading State Without Coupling to Option Names

To check Support Mode state from code that isn’t inside a hook callback, call SupportMode::is_active() (from Benecaster\Admin\SupportMode) rather than reading the benecaster_support_mode_enabled option directly — the option name is an implementation detail, the method is the contract.

Logging gated on this check never writes to disk when Support Mode is off, so add-ons can be as verbose as they like inside the gate.

Notes

The enable hook fires on every enable — including after a previous manual or auto-disable. If you schedule a cleanup cron, always call wp_clear_scheduled_hook() before wp_schedule_single_event() to avoid duplicate events.
The disable hook fires from both the manual toggle and the 7-day cron. The reason it passes — manual or auto — is informational; most add-ons handle both paths identically and tear down regardless.
If your add-on writes to Benecaster’s benecaster_debug_log table directly, those entries are automatically included in the diagnostic snapshot. You don’t need to buffer them separately — just gate them on SupportMode::is_active().

benecaster_support_mode_log_limit — raise the snapshot entry cap if your add-on emits a high volume of log entries
Capture More Log Entries in the Support Mode Diagnostic Snapshot — adjusting snapshot size

Code

<?php
add_action(
    'benecaster_support_mode_enabled',
    function ( int $auto_disable_at ): void {
        update_option( 'my_addon_verbose_logging', true, false );
        // Optional: schedule a parallel cleanup so the add-on never logs past
        // the same cutoff Benecaster uses, even if its cron is rescheduled.
        wp_clear_scheduled_hook( 'my_addon_support_mode_cleanup' );
        wp_schedule_single_event( $auto_disable_at, 'my_addon_support_mode_cleanup' );
    }
);

add_action(
    'benecaster_support_mode_disabled',
    function ( string $reason ): void {
        // $reason is 'manual' when the admin toggled off, 'auto' when the
        // 7-day cron fired. Tear down regardless.
        update_option( 'my_addon_verbose_logging', false, false );
        wp_clear_scheduled_hook( 'my_addon_support_mode_cleanup' );
    }
);

View on GitHub →