{"id":15528166,"url":"https://github.com/brianhenryie/bh-wp-logger","last_synced_at":"2026-06-13T07:01:00.126Z","repository":{"id":71001809,"uuid":"312743642","full_name":"BrianHenryIE/bh-wp-logger","owner":"BrianHenryIE","description":"Zero-config log UI for WordPress plugins","archived":false,"fork":false,"pushed_at":"2026-06-13T02:08:33.000Z","size":5105,"stargazers_count":19,"open_issues_count":7,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-06-13T04:04:32.884Z","etag":null,"topics":["psr","psr-3","wordpress"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BrianHenryIE.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-11-14T04:17:40.000Z","updated_at":"2026-06-13T02:00:31.000Z","dependencies_parsed_at":"2026-06-13T04:00:57.155Z","dependency_job_id":null,"html_url":"https://github.com/BrianHenryIE/bh-wp-logger","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/BrianHenryIE/bh-wp-logger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrianHenryIE%2Fbh-wp-logger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrianHenryIE%2Fbh-wp-logger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrianHenryIE%2Fbh-wp-logger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrianHenryIE%2Fbh-wp-logger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BrianHenryIE","download_url":"https://codeload.github.com/BrianHenryIE/bh-wp-logger/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrianHenryIE%2Fbh-wp-logger/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34275068,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["psr","psr-3","wordpress"],"created_at":"2024-10-02T11:11:03.801Z","updated_at":"2026-06-13T07:01:00.077Z","avatar_url":"https://github.com/BrianHenryIE.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![PHPUnit ](.github/coverage.svg)](https://brianhenryie.github.io/bh-wp-emails/) ![PHP 7.4](https://img.shields.io/badge/PHP-7.4-8892BF.svg)\n\n# BH WP Logger\n\nZero-config logger UI for WordPress plugins.\n\n```php\n$logger = Logger::instance();\n```\n\nWraps existing [PSR-3](https://www.php-fig.org/psr/psr-3/) loggers and adds some UI.\n\n* [KLogger](https://github.com/katzgrau/KLogger)\n* [WC_Logger](https://github.com/woocommerce/woocommerce/blob/trunk/includes/class-wc-logger.php)\n* [PSR-3 NullLogger](https://github.com/php-fig/log/blob/master/Psr/Log/NullLogger.php)\n\nUses KLogger by default, WC_Logger when specified, NullLogger when log level is set to \"none\".\n\nUses PHP's `set_error_handler()` to catch PHP deprecated/warning/notice/errors.\n\nHook into WordPress's deprecated function hooks (`deprecated_function_run` etc.) to log those only once per day.\n\nUses PHP's `register_shutdown_function()` to catch Exceptions related to the plugin.\n\nDeletes log files older than 30 days on cron.\n\nRecords a full backtrace on errors. Records two steps of backtrace on every log when the level is Debug.\n\n## UI \n\nDisplays logs in `WP_List_Table`.\n\n![Logs WP_List_Table](./.github/logs-wp-list-table.png \"Logs WP_List_Table\")\n\nShows a dismissible admin error notice each time there is a new error.\n\n![Admin Error Notice](./.github/admin-error-notice.png \"Admin error notice\")\n\nAdds a link to the logs view on the plugin's entry on plugins.php.\n\n![Plugins page logs link](./.github/plugins-page-logs-link.png \"Plugins page logs link\")\n\nWhen 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.\n\nSimilarly, any post type can be linked with `` `post_type_name:123` ``, e.g. `` `shop_order:123` `` will link to the WooCommerce order.\n\n![Links in log message](./.github/links-in-logs.png \"Log messages link to user or post\")\n\n\n## Use\n\n### Composer\n\n```\ncomposer require brianhenryie/bh-wp-logger\n```\n\nExpect breaking changes with every release until v1.0.0.\n\n### Instantiate\n\nYou should use [brianhenryie/strauss](https://github.com/BrianHenryIE/strauss) to prefix the library's namespace. Then Strauss's autoloader will include the files for you.\n\nThe following will work, but it will be faster and more reliable to provide the settings:\n\n```php\n$logger = Logger::instance();\n```\n\nProvide the settings:\n\n```php\n$logger_settings = new class() implements BrianHenryIE\\WP_Logger\\API\\Logger_Settings_Interface {\n    use BrianHenryIE\\WP_Logger\\Logger_Settings_Trait;\n    \n\tpublic function get_log_level(): string {\n\t\treturn LogLevel::INFO;\n\t}\n\n\t// This is used in admin notices.\n\tpublic function get_plugin_name(): string {\n\t\treturn \"My Plugin Name\";\n\t}\n\n\t// This is used in option names and URLs.\n\tpublic function get_plugin_slug(): string {\n\t\treturn \"my-plugin-name\";\n\t}\n\n\t// This is needed for the plugins.php logs link.\n\tpublic function get_plugin_basename(): string {\n\t\treturn \"my-plugin-name/my-plugin-name.php\";\n\t}\n};\n$logger = Logger::instance( $logger_settings );\n```\n\nThen pass around your `$logger` instance.\n\nAfter the logger has been instantiated once, subsequent calls to `::instance()` return the existing instance and any `$logger_settings` passed is ignored.\n\nTo use WooCommerce's native `WC_Logger`, use the `WooCommerce_Logger_Interface` interface (which just extends `Logger_Settings_Interface`) on the settings object.\n\n```php\n$logger_settings = new class() implements BrianHenryIE\\WP_Logger\\WooCommerce\\WooCommerce_Logger_Settings_Interface {\n    ...\n```\n\n### WooCommerce Settings\n\nSomething like this can be used for WooCommerce Settings API.\n\n```php\n\n$log_levels        = array( 'none', LogLevel::ERROR, LogLevel::WARNING, LogLevel::NOTICE, LogLevel::INFO, LogLevel::DEBUG );\n$log_levels_option = array();\nforeach ( $log_levels as $log_level ) {\n    $log_levels_option[ $log_level ] = ucfirst( $log_level );\n}\n\n$setting_fields[] = array(\n    'title'    =\u003e __( 'Log Level', 'text-domain' ),\n    'label'    =\u003e __( 'Enable Logging', 'text-domain' ),\n    'type'     =\u003e 'select',\n    'options'  =\u003e $log_levels_option,\n    'desc'    =\u003e __( 'Increasingly detailed levels of logs. ', 'text-domain' ) . '\u003ca href=\"' . admin_url( 'admin.php?page=plugin-slug-logs' ) . '\"\u003eView Logs\u003c/a\u003e',\n    'desc_tip' =\u003e false,\n    'default'  =\u003e 'notice',\n    'id'       =\u003e 'text-domain-log-level',\n);\n```\n\n![WooCommerce Settings](./.github/woocommerce-settings.png \"WooCommerce Settings\")\n\n## Filters\n\nTwo filters are present, to modify the log data as it is being saved, and to modify the log data as it is being presented.\n\nE.g. change the log level for specific log messages:\n\n```php\n/**\n * Modify the log data array or return null to cancel logging this entry.\n * The library php-http/logger-plugin is using INFO for detailed logging, let's change that to DEBUG.\n *\n * @hooked {$plugin_slug}_bh_wp_logger_log\n * \n * @pararm array{level:string,message:string,context:array} $log_data\n * @param Logger_Settings_Interface $settings\n * @param BH_WP_PSR_Logger $bh_wp_psr_logger\n */\nfunction modify_log_data( array $log_data, \\BrianHenryIE\\WP_Logger\\Logger_Settings_Interface $settings, \\BrianHenryIE\\WP_Logger\\API\\BH_WP_PSR_Logger $bh_wp_psr_logger): ?array {\n    \n    if ( 0 === strpos( $log_data['message'], 'Sending request' ) ) {\n        $log_data['level'] = LogLevel::DEBUG;\n    }\n\n    return $log_data;\n}\nadd_filter( \"{$plugin_slug}_bh_wp_logger_log\", 'modify_log_data', 10, 3 );\n```\n\nE.g. turn text in logs into hyperlinks as it is being displayed in the logs table:\n\n```php\n/**\n * Update ` `wc_order:123` ` with links to the order.\n * Use preg_replace_callback to find and replace all instances in the string.\n *\n * @hooked {$plugin_slug}_bh_wp_logger_column\n *\n * @param string                                                          $column_output The column output so far.\n * @param array{time:string, level:string, message:string, context:array} $item The log entry row.\n * @param string                                                          $column_name The current column name.\n * @param Logger_Settings_Interface                                       $logger_settings The logger settings.\n * @param BH_WP_PSR_Logger                                                $bh_wp_psr_logger The logger API instance.\n *\n * @return string\n */\nfunction replace_wc_order_id_with_link( string $column_output, array $item, string $column_name,\\BrianHenryIE\\WP_Logger\\Logger_Settings_Interface $logger_settings, \\BrianHenryIE\\WP_Logger\\API\\BH_WP_PSR_Logger $bh_wp_psr_logger ): string {\n\n    if ( 'message' !== $column_name ) {\n        return $column_output;\n    }\n\n    $callback = function( array $matches ): string {\n\n        $url  = admin_url( \"post.php?post={$matches[1]}\u0026action=edit\" );\n        $link = \"\u003ca href=\\\"{$url}\\\"\u003eOrder {$matches[1]}\u003c/a\u003e\";\n\n        return $link;\n    };\n\n    $message = preg_replace_callback( '/`wc_order:(\\d+)`/', $callback, $column_output ) ?? $column_output;\n\n    return $message;\n}\nadd_filter( \"{$plugin_slug}_bh_wp_logger_column\", 'replace_wc_order_id_with_link', 10, 5 );\n```\n\n## WP_Mock\n\nIf using WP_Mock for your tests, and you are instantiating this logger, the following should help:\n\n```php\n\\Patchwork\\redefine(\n    array( Logger::class, '__construct' ),\n    function( $settings ) {}\n);\n```\n\n### Test Plugin\n\nThe `test-plugin` folder contains a small plugin with buttons to trigger the types of errors that can be logged.\n\n![Test Plugin](./.github/test-plugin.png \"Test Plugin\")\n\n### Best Practice\n\nFrom 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.\n\n## TODO\n\n* ~~Check log directory is not publicly accessible~~\n* Check uploads dir chmod (is writable). =\u003e see [brianhenryie/bh-wp-private-uploads](https://github.com/BrianHenryIE/bh-wp-private-uploads)\n* Add current user to context\n* ~~Don't log empty context (WC)~~\n* Option for what level of errors to display as admin notices\n* Option for user capability for displaying admin notices (filter, at least)\n* ~~Zero-config WC_Logger: detect \"wc\", \"woo\" in plugin names~~\n* ~~Use [Code prettify](https://github.com/googlearchive/code-prettify) on the context json~~ : Used [caldwell/renderjson](https://github.com/caldwell/renderjson)\n* Paging and filtering\n* ~~Hyperlinks in messages~~\n* ~~Record timestamp the logs were last viewed at, make the plugins.php link bold if new logs are present.~~\n* ~~Auto-delete old logs~~\n* ~~Log notice should dismiss when the log page is visited~~\n* ~~Redact sensitive data. e.g. use `userid:123` in the saved logs and replace it with richer data when displaying them~~\n* Add errors to dashboard Site Health widget\n* Ensure output is properly escaped\n\nMinor concerns:\n* Debug logging could maybe be moved to a shutdown handler\n* Transients to suppress duplicate logs might be inefficient\n\n# Status\n\nTo 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. \n\nI'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.\n\nI think that's higher code-quality than most WordPress plugins.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrianhenryie%2Fbh-wp-logger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrianhenryie%2Fbh-wp-logger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrianhenryie%2Fbh-wp-logger/lists"}