Download the PHP package brianhenryie/bh-wp-logger without Composer

Wraps existing PSR-3 loggers and adds some UI.

• KLogger
• WC_Logger
• PSR-3 NullLogger

Uses KLogger by default, WC_Logger when specified, NullLogger when log level is set to "none".

Uses PHP's set_error_handler() to catch PHP deprecated/warning/notice/errors.

Hook into WordPress's deprecated function hooks (deprecated_function_run etc.) to log those only once per day.

Uses PHP's register_shutdown_function() to catch Exceptions related to the plugin.

Deletes log files older than 30 days on cron.

Records a full backtrace on errors. Records two steps of backtrace on every log when the level is Debug.

UI

Displays logs in WP_List_Table.

Shows a dismissible admin error notice each time there is a new error.

Adds a link to the logs view on the plugin's entry on plugins.php.

When log messages contain `wp_user:123` (NB: surrounded by single backticks) it will be replaced with a link to the user profile. This allows for logging useful references to users without logging their PII.

Similarly, any post type can be linked with `post_type_name:123`, e.g. `shop_order:123` will link to the WooCommerce order.

Use

Composer

Expect breaking changes with every release until v1.0.0.

Instantiate

You should use brianhenryie/strauss to prefix the library's namespace. Then Strauss's autoloader will include the files for you.

The following will work, but it will be faster and more reliable to provide the settings:

Provide the settings:

Then pass around your $logger instance.

After the logger has been instantiated once, subsequent calls to ::instance() return the existing instance and any $logger_settings passed is ignored.

To use WooCommerce's native WC_Logger, use the WooCommerce_Logger_Interface interface (which just extends Logger_Settings_Interface) on the settings object.

WooCommerce Settings

Something like this can be used for WooCommerce Settings API.

Filters

Two filters are present, to modify the log data as it is being saved, and to modify the log data as it is being presented.

E.g. change the log level for specific log messages:

E.g. turn text in logs into hyperlinks as it is being displayed in the logs table:

WP_Mock

If using WP_Mock for your tests, and you are instantiating this logger, the following should help:

Test Plugin

The test-plugin folder contains a small plugin with buttons to trigger the types of errors that can be logged.

Best Practice

From my limited logging experience, I find it useful to add a debug log at the beginning of functions and an appropriate info...error as the function returns.

TODO

• Check log directory is not publicly accessible
• Check uploads dir chmod (is writable). => see brianhenryie/bh-wp-private-uploads
• Add current user to context
• Don't log empty context (WC)
• Option for what level of errors to display as admin notices
• Option for user capability for displaying admin notices (filter, at least)
• Zero-config WC_Logger: detect "wc", "woo" in plugin names
• Use Code prettify on the context json : Used caldwell/renderjson
• Paging and filtering
• Hyperlinks in messages
• Record timestamp the logs were last viewed at, make the plugins.php link bold if new logs are present.
• Auto-delete old logs
• Log notice should dismiss when the log page is visited
• Redact sensitive data. e.g. use userid:123 in the saved logs and replace it with richer data when displaying them
• Add errors to dashboard Site Health widget
• Ensure output is properly escaped

Minor concerns:

• Debug logging could maybe be moved to a shutdown handler
• Transients to suppress duplicate logs might be inefficient

Status

To date I think it has been used mostly by me, i.e. internal projects. There are no egregious issues. It should work for everyone but I would like some feedback from others on how well it works for you.

I'll start at Semver 1.0.0 once I've caught up with WPCS, PhpStan and PhpUnit. There's about 65 tests and 43% coverage. WPCS + PHPStan are both pretty good.

I think that's higher code-quality than most WordPress plugins.