LoggerLayoutPattern - Apache log4php

Parameters

The following parameters are available:

Parameter	Type	Required	Default	Description
conversionPattern	string	No	%m%n	String which controls the output. See full specification below.

Conversion patterns

This is the string which controls formatting and consists of a mix of literal content and conversion specifiers.

The conversion pattern is closely related to the conversion pattern of the printf function in C. It is composed of literal text and format control expressions called conversion specifiers. You are free to insert any literal text within the conversion pattern.

Each conversion specifier starts with a percent sign (%) and is followed by optional format modifiers and a conversion character. The recognized conversion specifiers are:

Conversion character	Converts to
`%c` `%c{<precision>}`	Name of the Logger object which recieved the logging request. Optionally, it can be can followed by precision specifier, which is a decimal constant in brackets. If a precision specifier is given, then only the corresponding number of right most components of the logger name will be printed. For example, if the logger is named `foo.bar.Baz`, then `%c` will be translated to the full logger name, `%c{2}` will be translated to `bar.Baz`, and `%c{1}` will be translated to `Baz`.
`%C` `%C{<precision>}`	The fully qualified class name of the caller issuing the logging request. Currently, this will always return "Logger".
`%d` `%d{<format>}`	The date of the logging event. Optionally, may be followed by a date format specifier enclosed between braces. The format specifier follows the PHP date function. If no date format specifier is given then ISO8601 format is assumed (Y-m-d H:i:s,u). For example: `%d{Y-m-d H:i:s}`
`%F`	Name of the file from which the logging request was issued.
`%l`	Location information of the caller which generated the logging event. Identical to `%C.%M(%F:%L)`
`%L`	The line number at which the logging request was issued.
`%m`	The message associated with the logging event.
`%n`	A platform dependent line-break character(s). Note that a line break will not be printed unless explicitely specified.
`%M`	The method or function name from which the logging request was issued.
`%p`	The level of the logging event.
`%r`	The number of milliseconds elapsed since the start of the application until the creation of the logging event.
`%t`	The ID of the process that generated the logging event.
`%x`	The NDC (Nested Diagnostic Context) associated with the thread that generated the logging event.
`%X{<key>}`	The MDC (Mapped Diagnostic Context) associated with the thread that generated the logging event. The X conversion character must be followed by the MDC key in braces. The value in the MDC corresponding to the key will be output.
`%%`	A single percent sign.

Format modifiers

By default the relevant information is output as-is. However, with the aid of format modifiers it is possible to change the minimum and maximum width and the justifications of each data field.

All format modifiers are optional, and are placed between the percent sign and the conversion character.

The first format modifier is the left justification flag which is just the minus (-) character.

Then comes the >minimum field width modifier. This is an integer that represents the minimum number of characters to output. If the data item requires fewer characters, it is padded on either the left or the right until the minimum width is reached. The default is to pad on the left (right justify) but you can specify right padding with the left justification flag. The padding character is space. If the data item is larger than the minimum field width, the field is expanded to accommodate the data. The value is never truncated.

This behavior can be changed using the maximum field width modifier which is designated by a period (.) followed by an integer. If the data item is longer than the maximum field, then the extra characters are removed from the beginning of the data item and not from the end. For example, it the maximum field width is eight and the data item is ten characters long, then the first two characters of the data item are dropped. This behavior deviates from the printf function in C where truncation is done from the end.

The following table demonstrates various uses of format modifiers:

Format modifier	Justification	Minimum width	Maximum width	Comment
`%c`	none	none	none	Output the logger name as-is.
`%20c`	right	20	none	Left pad with spaces if the logger name is less than 20 characters long.
`%-20c`	left	20	none	Right pad with spaces if the logger name is less than 20 characters long.
`%.30c`	none	none	30	Truncate from the beginning if the logger name is longer than 30 characters.
`%20.30c`	right	20	30	Left pad with spaces if the logger name is shorter than 20 characters. However, if the logger name is longer than 30 characters, then truncate from the beginning.
`%-20.30c`	true	20	30	Right pad with spaces if the logger name is shorter than 20 characters. However, if the logger name is longer than 30 characters, then truncate from the beginning.

Examples

The following configuration configures a LoggerAppenderEcho which uses the pattern layout. All examples will use the same code and configuration, only the conversion pattern will change.

Save the configuration to a file called layout_pattern.xml.

XML
PHP

<configuration xmlns="http://logging.apache.org/log4php/">
    <appender name="default" class="LoggerAppenderEcho">
        <layout class="LoggerLayoutPattern">
            <param name="conversionPattern" value="%d{Y-m-d H:i:s.u} %c %-5p %m%n" />
        </layout>
    </appender>
    <root>
        <appender_ref ref="default" />
    </root>
</configuration>

array(
    'appenders' => array(
        'default' => array(
            'class' => 'LoggerAppenderEcho',
            'layout' => array(
                'class' => 'LoggerLayoutPattern',
                'params' => array(
                    'conversionPattern' => '%d{Y-m-d H:i:s.u} %c %-5p %m%n'
                )
            )
        )
    ),
    'rootLogger' => array(
        'appenders' => array('default')
    ),
)

Run the following code:

Logger::configure("layout_pattern.xml");
$logger = Logger::getLogger('myLogger');
$logger->info("Lorem ipsum dolor sit amet, consectetur adipiscing elit.");
$logger->debug("Donec a diam lectus.");
$logger->warn("Sed sit amet ipsum mauris.");

Pattern example

Conversion pattern: %d %c %-5p %m%n

Produces the following output:

2011-09-28 09:29:38,602 myLogger INFO  Lorem ipsum dolor sit amet, consectetur adipiscing elit.
2011-09-28 09:29:38,603 myLogger DEBUG Donec a diam lectus.
2011-09-28 09:29:38,604 myLogger WARN  Sed sit amet ipsum mauris.

In this example, %d produces the event datetime in default format (Y-m-d H:i:s,u), and %-5p produces the event level right padded to 5 characters. Since longest level name is 5 characters long, this ensures that the message always starts at the same character position which improves log readability.