README

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

Requirements

PHP ^7.2 || ^8.0
monolog/monolog ^2.5

Current stable releases target the Monolog 2 line. Monolog 3 support remains planned for a future major release.

Installation

composer require mhcg/monolog-wp-cli

Usage

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

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:

$log->pushHandler(
    new WPCLIHandler(
        Logger::INFO,
        true,
        false,
        [
            Logger::NOTICE => [
                'method' => 'warning',
                'includeLevelName' => true,
            ],
        ]
    )
);

<?php

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

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

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\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( Logger::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 WPCLIHandler reference.

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

Composer script quick reference:

test: run PHPUnit tests.
test:runtime-smoke: run fast runtime contract smoke checks.
wp:env:up: start local WordPress integration containers.
test:wp:setup: bootstrap WordPress and activate fixture plugin.
test:wp:smoke: run WP-CLI integration smoke checks.
test:wp: run wp:env:up, test:wp:setup, and test:wp:smoke.
wp:env:down: stop integration containers and remove volumes.
lint: run PHPMD and PHPCS.
qa: run PHPUnit plus lint checks.

Run WordPress integration checks step-by-step:

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.

CI runs on pull requests and pushes to main. The PHP workflow validates Composer metadata, runs runtime compatibility smoke checks on PHP 7.2 through 8.4, runs PHPUnit unit tests on PHP 7.2 through 8.4 using a compatible PHPUnit line per PHP version, and runs dependency audit, PHPMD, and PHPCS on PHP 8.3. A separate WordPress integration workflow provisions WordPress with WP-CLI and runs the integration smoke checks.

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 also welcome through the project wiki.

Please follow the Code of Conduct.

Support

Issues: https://github.com/markheydon/monolog-wp-cli/issues
Wiki: https://github.com/markheydon/monolog-wp-cli/wiki
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

Statistics

Security