Custom logging with wpdt_log()

WP Debug Toolkit (WPDT) provides wpdt_log(), a global helper function for writing structured log entries from your own code. It supports log levels, context labels, and automatic serialization of arrays and objects.

Function signature

wpdt_log( $message, string $context = 'custom', string $level = 'debug' ): void

Parameters

$message (mixed)

The value to log. Accepts strings, numbers, arrays, and objects.

• Strings and numbers are logged as-is.
• Arrays and objects are automatically encoded to JSON via wp_json_encode(). If JSON encoding fails, the function falls back to print_r().

$context (string)

A short identifier for the source of the log entry. Appears in the log output and is useful for filtering in the viewer’s search box. Default: 'custom'.

Examples: 'my-plugin', 'checkout', 'api', 'cron', 'import'.

$level (string)

The severity level of the log entry. Default: 'debug'.

Examples

// Log a simple message
wpdt_log( 'Payment processed', 'checkout', 'info' );

// Log structured data — automatically JSON-encoded
wpdt_log( $order_data, 'checkout', 'debug' );

// Log an error condition
wpdt_log( 'Stripe API timeout after 30s', 'payments', 'error' );

// Log with default level (debug) and default context (custom)
wpdt_log( 'Reached the sync function' );

// Log an array
wpdt_log( [ 'user_id' => 42, 'action' => 'export', 'rows' => 1500 ], 'data-export', 'info' );

Log level filtering

WPDT has a configurable log level threshold. Messages below the threshold are suppressed — the function returns without writing anything.

The level hierarchy from lowest to highest:

debug < info < warning < error

If the plugin log level is set to warning, only warning and error messages are written to debug.log. Calls with 'debug' or 'info' are silently skipped.

Configure the log level at Settings > Viewer > Error Log Level.

Safety when WPDT is not active

The wpdt_log() function is defined inside a function_exists() guard. If WPDT is deactivated or not installed, the function does not exist and calls to it produce a fatal error — unless you wrap them:

if ( function_exists( 'wpdt_log' ) ) {
    wpdt_log( 'Cache cleared', 'my-plugin', 'info' );
}

This pattern is safe to leave in production code. When WPDT is active, messages are logged. When WPDT is absent, the call is skipped with no overhead.

Comparison with alternatives

error_log()

PHP’s built-in error_log() writes directly to whatever log file PHP is configured to use. It works without WPDT or any plugin. However, it has no concept of log levels, context labels, or automatic data serialization. Use it when your code must work in environments where WPDT may not be present and you do not want to add the function_exists() wrapper.

error_log( '[my-plugin] Cache cleared' );

\DebugToolkit\Error_Handler::log()

The Error_Handler::log() static method is the internal logging API that wpdt_log() delegates to. It accepts the same level constants and context strings. Using it directly creates a tighter coupling to WPDT’s namespace and class structure. Use it only within WPDT’s own codebase or when you need access to additional Error_Handler methods like log_exception().

\DebugToolkit\Error_Handler::log( 'Cache cleared', 'my-plugin', \DebugToolkit\Error_Handler::LEVEL_INFO );

When to use each

• wpdt_log() — use for most cases. It is the simplest API, handles serialization, and respects level filtering.
• error_log() — use in code that must work without WPDT, such as standalone scripts, mu-plugins that load before WPDT, or libraries shared across projects.
• Error_Handler::log() — use only inside WPDT’s own code or when you need log_exception() for exception handling.