Monolog WP-CLI Handler

Extension for Monolog that routes log output through WP-CLI when running wp commands.

Installation

composer require mhcg/monolog-wp-cli

Requirements

• PHP ^8.1
• monolog/monolog ^3.0

Current stable releases target the Monolog 3 line. The v2.x branch is maintained separately for Monolog 2 users and receives critical fixes.

Official WordPress-runtime support is maintained separately from the package runtime floor. The current policy supports the current and previous WordPress major series through an explicit smoke-test tuple list rather than a blanket WordPress/PHP cross-product claim.

Usage

WPCLIHandler works like any other Monolog handler. Create the handler and push it onto a logger inside a WP-CLI command context.

By default the handler uses message-only output. Monolog context and extra data are only rendered when verbose formatting is enabled, either by passing true as the third WPCLIHandler constructor argument or when WP_DEBUG is enabled.

Version note (v2.2)

From v2.2, default NOTICE handling changed from WP_CLI::warning() to WP_CLI::log().

• Before v2.2: notice messages were shown as Warning: output.
• From v2.2: notice messages are logged as normal output with (NOTICE) level prefix.

If you need previous behaviour, pass a custom logger map override as the fourth WPCLIHandler constructor argument:

useMonolog\Level;
$log->pushHandler(
newWPCLIHandler(
Level::Info,
true,
false,
[
Level::Notice->value => [
'method' => 'warning',
'includeLevelName' => true,
],
]
)
);

<?phpuseMonolog\Level;
useMonolog\Logger;
useMHCG\Monolog\Handler\WPCLIHandler;
// Create a log channel.$log = newLogger('name');
$log->pushHandler(newWPCLIHandler(Level::Warning));
// Output to WP-CLI.$log->warning('This is a warning');
$log->error('An error has occurred');
$log->critical('This will report error and exit out');
$log->debug('Only shown when running wp with --debug');
$log->info('General logging - will not be shown when running wp with --quiet');

If you want Monolog context and extra data included in the output, enable verbose formatting:

$log->pushHandler(newWPCLIHandler(Level::Warning, true, true));
$log->warning('This includes context in verbose mode', ['job' => 'import']);

WordPress plugin-style example

The following example registers a mycommand WP-CLI command that writes log output through the handler.

This demonstrates the handler only. It is not a recommended project structure for building plugins or commands.

<?php/** * Plugin Name: My Plugin */// my-plugin.phpuseMonolog\Level;
useMonolog\Logger;
useMHCG\Monolog\Handler\WPCLIHandler;
// If this file is called directly, abort.if ( ! defined( 'ABSPATH' ) ) {
die;
}
// Autoload.$autoload = dirname( __FILE__ ) . '/vendor/autoload.php';
if ( file_exists( $autoload ) ) {
require_once$autoload;
}
// 'mycommand' WP-CLI command.if ( defined( 'WP_CLI' ) && WP_CLI ) {
functionmycommand_command( $args ) {
// Create logger.$log = newLogger( 'name' );
$log->pushHandler( newWPCLIHandler( Level::Info ) );
// Will only show when wp is run with --debug.$log->debug( 'Some geeky stuff' );
// These will not show when wp is run with --quiet.$log->info( 'Started running' );
$log->warning( 'Something happened of note' );
// Always shows even with --quiet.$log->error( 'An error has occurred' );
// No direct Monolog equivalent of WP_CLI::success.WP_CLI::success( 'Finished running mycommand' );
}
WP_CLI::add_command( 'mycommand', 'mycommand_command' );
}

wp mycommand
Started running
Warning: (WARNING) Something happened of note
Error: (ERROR) An error has occurred
Success: Finished running mycommand

wp mycommand --quiet
Error: (ERROR) An error has occurred

For full mapping and override details, see the WPCLIHandler reference.

Documentation

Full documentation is published at https://markheydon.me.uk/monolog-wp-cli/.

Development

Install dependencies:

composer install

Run local checks:

composer run test
composer run test:runtime-smoke
composer run test:wp
composer run lint
composer run qa

Run WordPress integration checks step-by-step (same as running composer run test:wp):

composer run wp:env:up
composer run test:wp:setup
composer run test:wp:smoke
composer run wp:env:down

Note: composer run test:wp does not call wp:env:down; run teardown explicitly when you are finished.

The local WordPress smoke workflow defaults to the repository's current baseline tuple. To run a different supported tuple, set WORDPRESS_VERSION and WORDPRESS_PHP_VERSION before running the WordPress scripts.

Example:

WORDPRESS_VERSION=6.8 WORDPRESS_PHP_VERSION=8.4 composer run test:wp

CI runs on pull requests and pushes to main.

• PHP CI validates Composer metadata, runs runtime smoke checks on PHP 8.1 to 8.5, runs unit tests across PHP 8.1 to 8.5 using a compatible PHPUnit line per PHP version, runs dependency audit, PHPMD, and PHPCS on PHP 8.3, and runs a dedicated WordPress smoke matrix for the repository's officially supported WordPress/PHP tuples.

For the reasoning behind the support window and tuple-based WordPress policy, see Compatibility and release-line policy.

Testing and code quality

• PHPUnit runs the test suite from tests/.
• PHPMD checks src/ for code-size and unused-code issues.
• PHPCS enforces PSR-12 across src/ and tests/.

Contributing

Fork the repository and open a pull request for code changes, referencing the related issue where relevant. For maintainer expectations, see CONTRIBUTING.

Documentation improvements are welcome via pull request. Edit website/content/ and preview with ./scripts/invoke-hugo-site.sh serve (or .\scripts\Invoke-HugoSite.ps1 serve on PowerShell). See CONTRIBUTING.

Please follow the Code of Conduct.

Support

• Documentation: https://markheydon.me.uk/monolog-wp-cli/
• Issues: https://github.com/markheydon/monolog-wp-cli/issues
• Source: https://github.com/markheydon/monolog-wp-cli

Licence

Released under the MIT licence. See LICENSE for details.