Apache log4php - Configuration

Configuration

Most components of log4php have various settings which determing their behaviour. They can all be configured programatically, but a much more common way is by providing the configuration options in a file.

Log4php understands three configuration formats: XML, PHP and Properties, all of which are covered in more details in the following sections.

The configuration is passed to log4php by calling the static method Logger::configure() before issuing any logging requests. In case log4php is not configured by the time a logging request is issued, log4php will configure itself using the default configuration.

XML

XML is the most common configuration format, and it is the most prominently featured in the documentation and examples.

A simple configuration looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns="http://logging.apache.org/log4php/">
    <appender name="default" class="LoggerAppenderFile">
        <layout class="LoggerLayoutSimple" />
        <param name="file" value="/var/log/my.log" />
        <param name="append" value="true" />
    </appender>
    <root>
        <appender_ref ref="default" />
    </root>
</configuration>

Detailed instructions on configuring each component is outlined in the corresponding compomnent's documentation: loggers, appenders, layouts, filters, renderers

PHP

Configuration can also be stored in a PHP array. This is the format used internally by log4php. All other formats are converted to a PHP array before being used by the configurator. Because of this, the PHP configuration format should be used when performance is important since it will avoid the overhead of parsing the ini or XML file.

This format can be used in one of two ways:

The configuration array can directly be passed to Logger::configure().

Logger::configure(array(
    'rootLogger' => array(
        'appenders' => array('default'),
    ),
    'appenders' => array(
        'default' => array(
            'class' => 'LoggerAppenderFile',
            'layout' => array(
                'class' => 'LoggerLayoutSimple'
            ),
            'params' => array(
            	'file' => '/var/log/my.log',
            	'append' => true
            )
        )
    )
));

Alternatively a file can be created which holds the PHP configuration array. The file must have the php extension and it should return the configuration array. For example, a file named config.php with the following content:

return array(
    'rootLogger' => array(
        'appenders' => array('default'),
    ),
    'appenders' => array(
        'default' => array(
            'class' => 'LoggerAppenderFile',
            'layout' => array(
                'class' => 'LoggerLayoutSimple'
            ),
            'params' => array(
            	'file' => '/var/log/my.log',
            	'append' => true
            )
        )
    )
);

This file can then be used to configure log4php:

Logger::configure('config.php');

Hint: to translate a XML or properties configuration file to PHP, run the following code:

$configurator = new LoggerConfiguratorDefault();
$config = $configurator->parse('/path/to/config.xml');

Properties (INI)

The properties configuration format is a legacy method of configuring log4php. It was inherited from Apache log4j and uses the same format. The only difference is that lines begin with log4php instead of log4j.

This format has been deprecated. Support will not be removed for the foreseeable future, however it may not be updated to include newly introduced features. It is recommended that you use either the XML or PHP configuration format.

The properites configuration format does not support filters.

The following is a high level overview of this format:

# Appender named "default"
log4php.appender.default = LoggerAppenderEcho
log4php.appender.default.layout = LoggerLayoutSimple

# Appender named "file"
log4php.appender.file = LoggerAppenderDailyFile
log4php.appender.file.layout = LoggerLayoutPattern
log4php.appender.file.layout.conversionPattern = %d{ISO8601} [%p] %c: %m (at %F line %L)%n
log4php.appender.file.datePattern = Ymd
log4php.appender.file.file = target/examples/daily_%s.log
log4php.appender.file.threshold = warn

# Root logger, linked to "default" appender
log4php.rootLogger = DEBUG, default

# Logger named "foo", linked to "default" appender
log4php.logger.foo = warn, default

# Logger named "foo.bar", linked to "file" appender
log4php.logger.foo.bar = debug, file
log4php.additivity.foo.bar = true

# Logger named "foo.bar.baz", linked to both "file" and "default" appenders
log4php.logger.foo.bar.baz = trace, default, file
log4php.additivity.foo.bar.baz = false

# Renderers for Fruit and Beer classes
log4php.renderer.Fruit = FruitRenderer
log4php.renderer.Beer = BeerRenderer

# Setting base threshold
log4php.threshold = debug

Default configuration

If no configuration is provided before the initial logging request is issued, log4php will configure using the default configuration. This consists of a single LoggerAppenderEcho appender, using LoggerLayoutSimple, attached to the root logger and set to the DEBUG level.

The default configuration in PHP format is:

array(
    'rootLogger' => array(
        'appenders' => array('default'),
    ),
    'appenders' => array(
        'default' => array(
            'class' => 'LoggerAppenderConsole',
            'layout' => array(
                'class' => 'LoggerLayoutSimple'
            )
        )
    )
)

Hint: You can fetch the default configuration as a PHP array by running:

LoggerConfiguratorDefault::getDefaultConfiguration();

Programmatic configuration

It is possible to configure log4php fully programmatically. This requires the user to implement their own configurator object. Configurators must implement the LoggerConfigurator interface.

Here is an example:

class MyConfigurator implements LoggerConfigurator {
	
    public function configure(LoggerHierarchy $hierarchy, $input = null) {

        // Create an appender which logs to file
        $appFile = new LoggerAppenderFile('foo');
        $appFile->setFile('D:/Temp/log.txt');
        $appFile->setAppend(true);
        $appFile->setThreshold('all');
        $appFile->activateOptions();
        
        // Use a different layout for the next appender
        $layout = new LoggerLayoutPattern();
        $layout->setConversionPattern("%date %logger %msg%newline");
        $layout->activateOptions();
        
        // Create an appender which echoes log events, using a custom layout
        // and with the threshold set to INFO 
        $appEcho = new LoggerAppenderEcho('bar');
        $appEcho->setLayout($layout);
        $appEcho->setThreshold('info');
        $appEcho->activateOptions();
        
        // Add both appenders to the root logger
        $root = $hierarchy->getRootLogger();
        $root->addAppender($appFile);
        $root->addAppender($appEcho);
    }
}

To use the configurator, pass it as a second parameter to Logger::configure() (either the name of the class as a string or an instance). Any value passed as $configuration will be available in the configure() method of the LoggerConfigurator as $input.

// User defined configuration (optional) 
$configuration = array(
    'foo' => 1,
    'bar' => 2
);

// Passing the configurator as string
Logger::configure($configuration, 'MyConfigurator');

// Passing the configurator as an instance
Logger::configure($configuration, new MyConfigurator());

Note: Always call activateOptions() on all appenders, filters and layouts after setting their configuration parameters. Otherwise, the configuration may not be properly activated.