README

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:

use Monolog\Level;

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

<?php

use Monolog\Level;
use Monolog\Logger;
use MHCG\Monolog\Handler\WPCLIHandler;

// Create a log channel.
$log = new Logger('name');
$log->pushHandler(new WPCLIHandler(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(new WPCLIHandler(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.php

use Monolog\Level;
use Monolog\Logger;
use MHCG\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 ) {

    function mycommand_command( $args ) {
        // Create logger.
        $log = new Logger( 'name' );
        $log->pushHandler( new WPCLIHandler( 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.

mhcg / monolog-wp-cli

Maintainers

Package info

Fund package maintenance!

Statistics

Security