6.11 Writing Loggers and Listeners

Use a listener to record build events or a logger to customize build output. These examples use the Phing 3 interfaces.

A listener implements Phing\Listener\BuildListener and receives events when a build, target, or task starts and finishes, and whenever a message is logged. A logger implements Phing\Listener\BuildLogger, which extends the listener interface with methods for configuring the output streams, message level, and Emacs mode. See Appendix I, Loggers and Listeners for Phing's built-in loggers and listeners.

6.11.1 Creating a Listener

A listener must implement all seven methods of the BuildListener interface. Leave methods empty for events you do not need. Each method receives a Phing\Listener\BuildEvent object, which provides access to the project and, where applicable, the target, task, message, priority, or exception.

This listener appends the date and build result to a file. Save it as BuildStatusListener.php in your project directory:

<?php

use Phing\Listener\BuildEvent;
use Phing\Listener\BuildListener;

class BuildStatusListener implements BuildListener
{
    public function buildStarted(BuildEvent $event)
    {
    }

    public function buildFinished(BuildEvent $event)
    {
        $status = $event->getException() === null ? 'SUCCESS' : 'FAILED';
        $line = date('c') . ' ' . $status . PHP_EOL;

        if (file_put_contents(__DIR__ . '/build-status.log', $line, FILE_APPEND | LOCK_EX) === false) {
            throw new RuntimeException('Unable to write build-status.log');
        }
    }

    public function targetStarted(BuildEvent $event)
    {
    }

    public function targetFinished(BuildEvent $event)
    {
    }

    public function taskStarted(BuildEvent $event)
    {
    }

    public function taskFinished(BuildEvent $event)
    {
    }

    public function messageLogged(BuildEvent $event)
    {
    }
}

The getException() method returns the build exception on failure, or null on success. Give the listener write access to its directory so it can create and update build-status.log.

Run the listener from your project directory:

phing -listener BuildStatusListener

The -listener option adds a listener alongside the normal build logger. Repeat the option to register additional listeners.

Note

Do not call Project::log() or Task::log() from messageLogged(). Those calls generate another message event and invoke the listener again. Write to a separate file or stream instead.

6.11.2 Creating a Logger

To customize build output, extend Phing\Listener\DefaultLogger. The parent class provides the listener methods, output streams, and message filtering. Override the methods for the behavior you want to change.

This logger adds a prefix to each message the default logger prints. Save it as PrefixedLogger.php in your project directory:

<?php

use Phing\Io\OutputStream;
use Phing\Listener\DefaultLogger;

class PrefixedLogger extends DefaultLogger
{
    protected function printMessage($message, OutputStream $stream, $priority)
    {
        parent::printMessage('[build] ' . $message, $stream, $priority);
    }
}

To select the logger, run:

phing -logger PrefixedLogger

The -logger option replaces the normal build logger. Combine it with -listener to use both examples in the same build:

phing -logger PrefixedLogger -listener BuildStatusListener

The call to parent::printMessage() uses the supplied stream to preserve the default logger's output routing, including -logfile. The inherited event methods apply the message level you select with -quiet, -verbose, or -debug.

If you implement BuildLogger directly, you must also implement setMessageOutputLevel(), setOutputStream(), setErrorStream(), and setEmacsMode(). Phing calls these methods to configure the logger before the build starts. Ignore messages whose priority exceeds the configured message level.

6.11.3 Loading Your Classes

These examples use classes without a namespace and assume that the current directory is on PHP's include_path. If you store the classes elsewhere, make them available through the include_path or an autoloader registered before Phing starts. For a namespaced class, pass the fully qualified class name, for example 'MyApp\Build\PrefixedLogger'.

Phing creates command-line loggers and listeners before executing the build file. Make their classes available at startup and provide constructors that Phing can call without arguments.