LoggerLayoutPattern

In-Reply-To: <33022fd6f25443dba3852df16be4c47a@git.apache.org> References: <33022fd6f25443dba3852df16be4c47a@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [08/43] LOG4PHP-121: Reorganized classes into namespaces http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/79ed2d0d/src/site/xdoc/docs/layouts/pattern.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/docs/layouts/pattern.xml b/src/site/xdoc/docs/layouts/pattern.xml deleted file mode 100644 index 7b3a6cf..0000000 --- a/src/site/xdoc/docs/layouts/pattern.xml +++ /dev/null @@ -1,655 +0,0 @@ - - - - - - LoggerLayoutPattern - - - -

- -

LoggerLayoutPattern is a flexible layout configurable via a conversion pattern.

- - -

The following parameters are available:

- - - - - - - - - - - - - - - - - - - - -

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

- -

Conversion patterns

- -

Conversion pattern is a string which controls the formatting of logging - events. It controls how logging events will be transformed into strings by the layout.

- -

The conversion pattern is closely related to the conversion pattern of the PHP - sprintf function. - It is composed of literal text and format control expressions called conversion specifiers. -

- -

A conversion specifier begins with a percent sign (%) and is followed by a conversion word. - Some conversion words require one or more options to be given. These are specified in braces after the - conversion word. An example of a conversion specifier is %message which will be converted into - the message from the logging event which is being logged.

- -

The recognized conversion specifiers are:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Conversion specifier Converts to

%c{length}

%lo{length}

%logger{length}

Name of the Logger which generated the logging request.

- -

Optionally, a desired output length can be specified. If given, the converter will attempt - to abbreviate the logger name without losing too much information in the process. If - zero length is specified, only the rightmost name fragment will be output.

- -

Specifying the desired length 0 means that only the class name will be returned without - the corresponding namespace.

- -

Several examples of the shortening algorithm in action:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Conversion specifier	Logger name	Result
%logger	org\apache\logging\log4php\Foo	org\apache\logging\log4php\Foo
%logger{0}	org\apache\logging\log4php\Foo	Foo
%logger{10}	org\apache\logging\log4php\Foo	o\a\l\l\Foo
%logger{20}	org\apache\logging\log4php\Foo	o\a\l\log4php\Foo
%logger{25}	org\apache\logging\log4php\Foo	o\a\logging\log4php\Foo
%logger{30}	org\apache\logging\log4php\Foo	org\apache\logging\log4php\Foo

- -

Note that rightmost segment will never be shortened. It is possible that the - resulting string will be longer than the specified desired length.

For backward compatibility, a dot can be used as a namespace separator, as well as - the backslash.

%C{length}

%class{length}

The fully qualified class name of the caller issuing the logging request.

Just like %logger, a desired length can be defined as an option.

%cookie{key}

A value from the $_COOKIE superglobal array corresponding to the given key.

If no key is given, will return all values in key=value format.

%d{pattern}

%date{pattern}

The date/time of the logging event. Accepts a pattern string as an option. The - pattern syntax is the same as used by the PHP's date() function.

- -

If no pattern is given, the date format will default to the ISO8601 datetime format, - which is the same as giving the pattern: c.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Conversion specifier	Result
%d	2011-12-27T12:01:32+01:00
%date	2011-12-27T12:01:32+01:00
%date{ISO8601}	2011-12-27T12:01:32+01:00
%date{Y-m-d H:i:s,u}	2011-12-27 12:01:32,610
%date{l jS \of F Y h:i:s A}	Tuesday 27th of December 2011 12:01:32 PM

%e{key}

%env{key}

A value from the $_ENV superglobal array corresponding to the given key.

If no key is given, will return all values in key=value format.

%ex

%exception

%throwable

The exception associated with the logging event, along with it's stack trace. If - there is no exception, evalutates to an empty string.

%file

Name of the file from which the logging request was issued.

%location

Location information of the caller which generated the logging event.

Identical to %C.%M(%F:%L)

%line

The line number at which the logging request was issued.

%msg

%message

The message associated with the logging event.

%method

The method or function name from which the logging request was issued.

%newline

A platform dependent line-break character(s).

Note that a line break will not be printed unless explicitely specified.

%le

%level

The level of the logging event.

%relative

The number of milliseconds elapsed since the start of the application until the creation of the logging event.

%req{key}

%request{key}

A value from the $_REQUEST superglobal array corresponding to the given key.

If no key is given, will return all values in key=value format.

%s{key}

%server{key}

A value from the $_SERVER superglobal array corresponding to the given key.

If no key is given, will return all values in key=value format.

%ses{key}

%session{key}

A value from the $_SESSION superglobal array corresponding to the given key.

If no key is given, will return all values in key=value format.

%sid

%sessionid

The active session ID, or an empty string if not in session.

Equivalent to calling session_id().

%pid

%process

The ID of the process that generated the logging event.

%ndc

The NDC (Nested Diagnostic Context) associated with the thread that generated the logging event.

%X{key}

%mdc{key}

A value from the Mapped Diagnostic Context (MDC) corresponding to the given key.

- - - -

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. -

- -

Both format modifiers are optional, and are placed between the percent sign (%) and the conversion - word. These are, in order:

- -

A minimum width specifier, a number which determines the minimum width of the resulting - string. If the resulting string is shorter that the given number, it will be padded with spaces to - the desired length. By default, the string is right-justified (padded from left), but adding a - "-" sign before the specifier will make it left-justified.
A maximum widht specifier, a dot (".") followed by a number which determines the maximum - allowed width of the resulting string. If the resulting string is shorter than the given number, it - will be truncated to the maximum width. By default the string is truncated from the right, but - adding a "-" sign before the specifier will cause it to truncate from the left.

- -

The following table demonstrates various uses of format modifiers:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Format modifier	Padding	Trimming	Minimum width	Maximum width	Comment
%logger	none	none	none	none	Output the logger name as-is.
%20logger	right	none	20	none	Left pad with spaces if the logger name is less than 20 characters long.
%-20logger	left	none	20	none	Right pad with spaces if the logger name is less than 20 characters long.
%.30logger	none	right	none	30	Trim from the end if the logger name is longer than 30 characters.
%.-30logger	none	left	none	30	Trim from the beginning if the logger name is longer than 30 characters.
%20.30logger	right	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 trim from the end.
%-20.30logger	left	right	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 trim from the end.

- -

The following table lists a couple of examples for using format modifiers. Note that the square - brackets are added to the conversion pattern to delimit the output.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Conversion pattern	Logger name	Result
[%10logger]	Foo	`[ Foo]`	Added padding, right aligned.
[%-10logger]	Foo	`[Foo ]`	Added padding, left aligned.
[%.10logger]	org.apache.log4php.Foo	`[org.apache]`	Trimmed from right.
[%.-10logger]	org.apache.log4php.Foo	`[og4php.Foo]`	Trimmed from left.

- - - -

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 from example to example.

- -

 array(
-        'default' => array(
-            'class' => 'LoggerAppenderEcho',
-            'layout' => array(
-                'class' => 'LoggerLayoutPattern',
-                'params' => array(
-                    'conversionPattern' => '%date %logger %-5level %msg%n'
-                )
-            )
-        )
-    ),
-    'rootLogger' => array(
-        'appenders' => array('default')
-    ),
-)
-]]>

- - -

Example code:

- -

-Logger::configure("config.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.");
-

- -

A simple example

- -

Conversion pattern: %date %logger %-5level %msg%n

- -

Running the example code produces the following output:

- -

-2012-02-27T19:42:17+01:00 myLogger INFO  Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-2012-02-27T19:42:17+01:00 myLogger DEBUG Donec a diam lectus.
-2012-02-27T19:42:17+01:00 myLogger WARN  Sed sit amet ipsum mauris.
-

- -

In this example, %date is converted to the event datetime in default format - (corresponding to the ISO-8601 specification), and %-5level 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.

- -

Notice that the newline between logging events (%n) has to be explicitely defined. Otherwise all - logging events will be logged in the same line.

- -

Formatting the date

- -

The %date conversion word can take the desired date format as an option. For example, - if you're European, the d.m.Y date format might be more familiar. Also, adding milliseconds.

- -

Conversion pattern: %date{d.m.Y H:i:s,u} %logger %-5level %msg%n

- -

Running the example code produces the following output:

- -

-27.02.2012 20:14:41,624 myLogger INFO  Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-27.02.2012 20:14:41,625 myLogger DEBUG Donec a diam lectus.
-27.02.2012 20:14:41,626 myLogger WARN  Sed sit amet ipsum mauris.
-

- -

Logging HTTP requests

- -

If log4php is used to log HTTP requests, a pattern like this might be useful:

- -

%date [%pid] From:%server{REMOTE_ADDR}:%server{REMOTE_PORT} Request:[%request] Message: %msg%n

- -

Request /test.php?foo=bar it will produce the output similar to:

- -

-2012-01-02T14:19:33+01:00 [22924] From:194.152.205.71:11257 Request:[foo=bar] Message: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-2012-01-02T14:19:33+01:00 [22924] From:194.152.205.71:11257 Request:[foo=bar] Message: Donec a diam lectus.
-2012-01-02T14:19:33+01:00 [22924] From:194.152.205.71:11257 Request:[foo=bar] Message: Sed sit amet ipsum mauris.
-

- -

%server{REMOTE_ADDR} is equivalent to PHP code $_SERVER['REMOTE_ADDR'].

- -

Logging exceptions

- -

If you wish to log any exception passed to the logging methods, you should add the %ex - specifier to the end of your conversion pattern, after %newline. This way, if an exception - is loggerd it will be addded to your log below your message.

- -

For example: %date %logger %message%newline%ex

- -

In the following code, suppose that the work() method can throw an exception. This wolud be a good - way to deal with it:

- -

-$log = Logger::getLogger('foo');
-$log->info("Let's try this");
-
-try
-{
-    $foo = new Foo();
-    $foo->work(123);
-}
-catch(Exception $ex)
-{
-    // Exception is passed as the second parameter
-    $log->error("That didn't work", $ex);
-}
-$log->info("Done.");
-

- -

If work() throws an exception, your log might look something like this:

- -

-2012-10-08T10:11:18+02:00 foo Let's try this
-2012-10-08T10:11:18+02:00 foo That didn't work
-exception 'Exception' with message 'Doesn't work' in D:\work\exceptions.php:38
-Stack trace:
-#0 D:\work\exceptions.php(29): Bar->work(123)
-#1 D:\work\exceptions.php(48): Foo->work(123)
-#2 {main}
-2012-10-08T10:11:18+02:00 foo Done.
-

- -

The exception, along with the full stack trace ends up in your log. This also works with nested - exceptions, the full stack trace is added.

- -

- - http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/79ed2d0d/src/site/xdoc/docs/layouts/serialized.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/docs/layouts/serialized.xml b/src/site/xdoc/docs/layouts/serialized.xml deleted file mode 100644 index adae267..0000000 --- a/src/site/xdoc/docs/layouts/serialized.xml +++ /dev/null @@ -1,122 +0,0 @@ - - - - - - LoggerLayoutSerialized - - - -

- -

LoggerLayoutSerialized formats the logging event using the PHP's - serialize() function.

- - -

The following parameters are available:

- - - - - - - - - - - - - - - - - - - - -

Parameter	Type	Required	Default	Description
locationInfo	boolean	No	false	If set to true, event's location information will be initialized before serialization. - Enabling this parameter makes logging slower and should be used only if required.

- - - - - -

Sample configuration file:

- -


-    
-        
-    
-    
-        
-    
-
-]]>

 array(
-        'default' => array(
-            'class' => 'LoggerAppenderEcho',
-            'layout' => array(
-                'class' => 'LoggerLayoutSerialized',
-            )
-        )
-    ),
-    'rootLogger' => array(
-        'appenders' => array('default')
-    ),
-)
-]]>

- -

Running the following code:

- -

-Logger::configure("config.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.");
-

- -

Produces the following output:

- -

- - -

- - http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/79ed2d0d/src/site/xdoc/docs/layouts/simple.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/docs/layouts/simple.xml b/src/site/xdoc/docs/layouts/simple.xml deleted file mode 100644 index 0e59715..0000000 --- a/src/site/xdoc/docs/layouts/simple.xml +++ /dev/null @@ -1,104 +0,0 @@ - - - - - - LoggerLayoutSimple - - - -

- -

LoggerLayoutSimple is a basic layout which outputs only the level followed by the message.

- -

It is interesting to note that the output of LoggerLayoutSimple is identical to that of - LoggerLayoutPattern with the conversion pattern set to - %p - %m%n.

- - - -

This layout does not have any configurable parameters.

- - - - -

Configuration:

- -


-    
-        
-    
-    
-        
-    
-
-]]>

 array(
-        'default' => array(
-            'class' => 'LoggerAppenderEcho',
-            'layout' => array(
-                'class' => 'LoggerLayoutSimple',
-            )
-        )
-    ),
-    'rootLogger' => array(
-        'appenders' => array('default')
-    ),
-)
-]]>

- - -

Running the following code:

- -

-Logger::configure("layout_xml.xml");
-$log = Logger::getRootLogger();
-$log->info("My first message.");
-$log->debug("My second message.");
-$log->warn("My third message.");
-

- -

Produces the following output:

- -

-INFO - My first message.
-DEBUG - My second message.
-WARN - My third message.
-

- - -

- - http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/79ed2d0d/src/site/xdoc/docs/layouts/ttcc.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/docs/layouts/ttcc.xml b/src/site/xdoc/docs/layouts/ttcc.xml deleted file mode 100644 index 4a797f9..0000000 --- a/src/site/xdoc/docs/layouts/ttcc.xml +++ /dev/null @@ -1,162 +0,0 @@ - - - - - - LoggerLayoutTTCC - - - -

- -

- Deprecated! -

LoggerLayoutTTCC is deprecated and will be removed in a future release. Please use - LoggerLayoutPattern instead.

- -

The TTCC layout format was taken from Apache log4j, and originally consisted of Time, Thread, Category - and nested diagnostic Context information, hence the name.

- -

LoggerLayoutTTCC contains equivalent information:

Time
Process ID
Logger name
Nested diagnostic context

- -

Output of LoggerLayoutTTCC is identical to that of - LoggerLayoutPattern with the conversion pattern set to - %d{m/d/y H:i:s,u} [%t] %p %c %x - %m%n.

- - - -

The following parameters are available:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Parameter	Type	Required	Default	Description
threadPrinting	boolean	No	true	If set to true, the process ID will be included in output.
categoryPrefixing	boolean	No	true	If set to true, the logger name will be included in output.
contextPrinting	boolean	No	true	If set to true, the nested diagnostic context will be included in output.
microSecondsPrinting	boolean	No	true	If set to true, the microseconds will be included in output.

- - - - -

Configuration:

- -


-    
-        
-    
-    
-        
-    
-
-]]>

 array(
-        'default' => array(
-            'class' => 'LoggerAppenderEcho',
-            'layout' => array(
-                'class' => 'LoggerLayoutTTCC',
-            )
-        )
-    ),
-    'rootLogger' => array(
-        'appenders' => array('default')
-    ),
-)
-]]>

- - -

For this example, some Nested Diagnostic Context is added also. Running the following code:

- -

-Logger::configure("config.xml");
-LoggerNDC::push("Some Context");
-
-$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.");
-

- -

Produces the following output:

- -

-02/20/12 23:36:39,772 [9820] INFO myLogger Some Context - Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-02/20/12 23:36:39,773 [9820] DEBUG myLogger Some Context - Donec a diam lectus.
-02/20/12 23:36:39,773 [9820] WARN myLogger Some Context - Sed sit amet ipsum mauris.
-

- -

- - http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/79ed2d0d/src/site/xdoc/docs/layouts/xml.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/docs/layouts/xml.xml b/src/site/xdoc/docs/layouts/xml.xml deleted file mode 100644 index 125c0d2..0000000 --- a/src/site/xdoc/docs/layouts/xml.xml +++ /dev/null @@ -1,189 +0,0 @@ - - - - - - LoggerLayoutXml - - - -

- -

LoggerLayoutXml formats the messages as an XML document.

- - -

The following parameters are available:

- - - - - - - - - - - - - - - - - - - - - - - - - - - -

Parameter	Type	Required	Default	Description
locationInfo	boolean	No	true	If set to true, adds the file name and line number at which the log statement originated.
log4jNamespace	boolean	No	false	If set to true then log4j XML namespace will be used instead of the log4php namespace. - This can be usefull when using log viewers which can only parse the log4j namespace such as - Apache Chainsaw.

- - - - -

Default configuration example

- -

The default configuration of LoggerLayoutXml will use the log4php XML namespace and - include the location information.

- -

Configuration file:

- -


-    
-        
-    
-    
-        
-    
-
-]]>

 array(
-        'default' => array(
-            'class' => 'LoggerAppenderEcho',
-            'layout' => array(
-                'class' => 'LoggerLayoutXml',
-            )
-        )
-    ),
-    'rootLogger' => array(
-        'appenders' => array('default')
-    ),
-)
-]]>

- - -

Running the following code:

- -

-Logger::configure("config.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.");
-

- -

Produces the following output:

- -


-
-
-]]>
-
-
-
-
-]]>
-
-
-
-
-]]>
-
-
-
-
-]]>

- - -

Overriding default options

- -

This example show how to configure LoggerLayoutXml to exclude the location information - and use the log4j XML namespace.

- -

Configuration file:

- -

Using this configuration will produce the following output:

- -


-
-]]>
-
-
-
-]]>
-
-
-
-]]>
-
-
-
-]]>

- - -

- - http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/79ed2d0d/src/site/xdoc/docs/loggers.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/docs/loggers.xml b/src/site/xdoc/docs/loggers.xml deleted file mode 100644 index 9892d4f..0000000 --- a/src/site/xdoc/docs/loggers.xml +++ /dev/null @@ -1,289 +0,0 @@ - - - - - - Loggers - - - -

- -

A logger is a component which will take your logging request and log it. Each class in a project can - have an individual logger, or they can all use a common logger. Loggers are named entities; it is - common to name them after the class which will use it for logging.

- -

Creating a logger is done by calling the static getLogger() method on the Logger object - and providing the name of the logger. For example, to create a logger named foo:

- -

$logger = Logger::getLogger('foo');

- -

Logging requests are made by invoking one of the printing methods of a Logger instance. These logging - methods are: trace, debug, info, warn, error and fatal. The printing method determines the level of a - logging request. For example, calling the method info() creates a logging request of level - INFO. For example:

- -

$logger->info("This is the message to be logged.");

- -

Loggers by themselves do not define where these messages will be logged. For that you need to assign - one or more appenders to the logger.

- - -

A logger can be assigned a threshold level. All logging requests with level lower than this threshold - will be ignored.

- -

For example, setting logger threshold to INFO means that logging requests with levels - TRACE and DEBUG will not be logged by this logger.

- -

An example of setting the root logger threshold to INFO:

- -


-    
-    
-        
-        
-    
-
-]]>

- -

If not explicitly configured, loggers will have their threshold level set to DEBUG by - default.

- - - -

Loggers can be individually configured in the configuration file.

- -

The simplest example is to configure the root logger, since all other loggers will inherit its - settings, as explained in the next section.

- -


-    
-    
-        
-        
-    
-
-]]>

This configuration adds the default appender to the root logger, and sets it's - threshold level to INFO.

- -

It is also possible to configure individual named loggers. For example, let's configure the - foo logger, used in the example above, and set it's threshold to WARN:

- -


-    
-    
-        
-        
-    
-
-]]>

- - - -

Loggers follow a parent-child relationship pattern which is implemented by using a naming pattern. - A logger is said to be an ancestor of another logger if its name followed by a dot is a - prefix of the descendant logger name. A logger is said to be a parent of a - child logger if there are no ancestors between itself and the descendant logger.

- -

For example, the logger named foo is a parent of the logger named foo.bar. - Similarly, org is a parent of org.apache and an ancestor of - org.apache.logging. This naming scheme should be familiar to most developers.

- -

The root logger resides at the top of the logger hierarchy. It is exceptional in two ways:

it always exists,
it cannot be retrieved by name.

- -

Invoking the class static Logger::getRootLogger() method retrieves the root logger. - All other loggers are instantiated and retrieved with the Logger::getLogger($name) - method. This method takes the name of the desired logger as a parameter. If the logger does not exist - at the time of the call, it will be created.

- - - -

The threshold level and appenders are inherited from the parent to the child loggers.

- -

For example examine the following configuration:

- -


-    
-    
-        
-        
-    
-
-]]>

- -

The threshold level of the root logger is set to debug. Also, the root logger is linked to a console - appender. Any named logger that is created will inherit these root settings.

- -

trace('This will not be logged.');
-$main->info('This will be logged.');
-]]>

A logger named main is created. Since there is no logger-specific configuration, it - will inherit all of it's settings from the root logger: a console appender, and threshold set to DEBUG. - Therefore, this code will produce the following output:

- -

INFO - This will be logged.

- - - -

Appender additivity is a property of loggers to inherit their parent's appenders. By default all - loggers have appender additivity enabled.

- -

Let's take the following example:

- -


-    
-    
-    
-        
-    
-     
-        
-    
-
-]]>

Since additivity is enabled by default, the logger foo will have two linked appenders: - A1 which it will inherit from the root logger, and A2 which is defined for it specifically.

- -

Therefore, by executing the following code:

- -

info('This will be logged twice.');
-]]>

The message will be logged twice - once by A1 and once by A2, producing:

- -

-INFO - This will be logged twice.
-INFO - This will be logged twice.
-

- -

Disabling appender additivity

- -

Logger's appender additivity can also be disabled if needed.

- -

If the foo logger in the previous example was configured like this:

- -

 
-    
-
-]]>

Then the logger would not have inherited the A1 appender from the root logger, and the message - would have been logged only once.

- -

A more complex example

- -

In this example we will look at multiple loggers making a hierarchy.

- -

Not to make the example too complex, all appenders will log to the console. Of course, this doesn't - always have to be the case.

- -

Let's take the following configuration file:

- -

The table below shows how the configuration is interpreted, and which appenders are inherited:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Logger name	Linked appenders	Additivity flag	Output targets	Comment
root	A1	N/A	A1	One appender, named A1, is added to root logger. Any logging requests to root logger - will be forwarded only to that one appender.
foo	A2, A3	true	A1, A2, A3	A logger named `foo` is created and two appenders, named A2 and A3, are - added to it. Additionally, because of logger additivity, `foo` inherits the - appender A1 from the root logger which is it's parent in the logger hierarchy. Therefore - logging requests to this logger will be forwarded to appenders A1, A2 and A3.
foo.bar	none	true	A1, A2, A3	A logger named `foo.bar` is created. Because it's name starts with - `foo`, it will be created as a child of the `foo` logger. - No appenders are added to `foo.bar` but it will inherit it's ancestor's - appenders: appenders A2 and A3 from `foo` and A1 from `root`. - Logging requests to this logger will be forwarded to appenders A1, A2 and A3.
foo.bar.baz	A4	false	A4	Finally, logger `foo.bar.baz` is created, and because of it's name it is - created as child to `foo.bar`. One appender, A4 is added to it. However, since - it's additivity flag is set to false, it will not inherit any appenders from it's - ancestors. Logging requests to this logger will be forwarded only to appender A4.

- -

- - http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/79ed2d0d/src/site/xdoc/docs/renderers.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/docs/renderers.xml b/src/site/xdoc/docs/renderers.xml deleted file mode 100644 index 6c1b921..0000000 --- a/src/site/xdoc/docs/renderers.xml +++ /dev/null @@ -1,218 +0,0 @@ - - - - - - Renderers - - - -

Apache log4php can log more than just string messages. If you try to log an object it will be converted - to a string and logged. The component which converts Objects to strings in log4php is called a - renderer.

- - - -

For example, let's say that an application uses a Person object, like this one:

- -

If you try logging it:

- -

firstName = 'John';
-$person->lastName = 'Doe';
-$person->age = 37;
-
-$logger = Logger::getLogger('main');
-$logger->info("Here comes the person:");
-$logger->info($person);
-]]>

Log4php will render it using the default renderer and you will end the output will look something - like:

- -

 John
-    [lastName] => Doe
-    [age] => 37
-)
-]]>

- - - - -

In order to make log4php log the Person object in a more readable format, a custom renderer - class can be defined which will convert Person objects to a string suitable for logging.

- -

Let's call this renderer class PersonRenderer.

- -

firstName} {$person->lastName} ({$person->age})";
-    }
-}
-]]>

- -

Now log4php has to be configured to use PersonRenderer for rendering Person objects. This is done - in the configuration file.

- -


-    
-    
-    
-        
-    
-
-]]>

 array(
-        array(
-            'renderedClass' => 'Person',
-            'renderingClass' => 'PersonRenderer'
-        )
-    ),
-    'appenders' => array(
-        'default' => array(
-            'class' => 'LoggerAppenderEcho',
-        ),
-    ),
-    'rootLogger' => array(
-        'appenders' => array('default'),
-    ),
-)
-]]>

- - -

If the same code is run as above, the following output is produced:

- -

Which is much more readable than the default rendering.

- - - -

It is possible to set your own custom renderer as the default renderer.

- -

For example, if you're not happy with the way in which the default renderer converts objects, - you can create your own renderer:

- -

And set it as the default renderer in the configuration:

- -


-    
-    
-    
-        
-    
-
-]]>

 'MyRenderer',
-    'appenders' => array(
-        'default' => array(
-            'class' => 'LoggerAppenderEcho',
-        ),
-    ),
-    'rootLogger' => array(
-        'appenders' => array('default'),
-    ),
-)
-]]>

- -

Logging a Person object using this configuration will make log4php fall back to the newly - defined default renderer, which uses var_dump instead of print_r, and - the result will look like:

- -


-  string(4) "John"
-  public $lastName =>
-  string(3) "Doe"
-  public $age =>
-  int(37)
-}
-]]>

- - - -

Object rendering follows the class hierarchy.

- -

For example, if there is a class named Fruit, and classes Orange, Lemon and Apple all extend Fruit. - When FruitRenderer is registered as renderer for the Fruit class, all subclasses of Fruit will also - be rendered by FruitRenderer. Of course, it is possible to override this by registering OrangeRenderer - as renderer for the Orange class.

- -

- - http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/79ed2d0d/src/site/xdoc/install.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/install.xml b/src/site/xdoc/install.xml deleted file mode 100644 index 82572c2..0000000 --- a/src/site/xdoc/install.xml +++ /dev/null @@ -1,89 +0,0 @@ - - - - - - Installing - - - -

- - - -

Download the latest source package from the download page and unpack it.

- -

The package directory structure is as follows:

- -

-├───apidocs      - API generated documentation
-└───src
-    ├───assembly - Maven assembly configuration 
-    ├───changes  - The change log
-    ├───examples - Various usage examples
-    ├───main  
-    │   └───php  - The main source code
-    ├───site     - Web site source
-    └───test     - Unit tests
-

Most users will primarily be interested in the source code which is located in - /src/main/php. The contents of this directory may be copied to a directory within your - project for easier access.

- - - - - -

Apache log4php has it's own PEAR channel.

- -

To install from the PEAR channel, execute the following commands:

- -

-pear channel-discover pear.apache.org/log4php
-pear install log4php/Apache_log4php
-

- - - - - -

Apache log4php is available from Packagist via Composer. Please note: this channel is not an official Apache Software Foundation channel, - but maintained from Apache log4php committers.

- -

To with compoers, add the following lines to composer.json:

- -

-"require": {
-    "apache/log4php": "2.3.0"
-}
-

Then run:

- -

-php composer.phar install
-

Or, if you have composer installed as binary:

- -

-composer install
-

- -

- - http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/79ed2d0d/src/site/xdoc/privacy.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/privacy.xml b/src/site/xdoc/privacy.xml deleted file mode 100644 index 523c79f..0000000 --- a/src/site/xdoc/privacy.xml +++ /dev/null @@ -1,53 +0,0 @@ - - - - - - Privacy policy - - - -

Information about your use of this web site is collected using server access logs and a tracking cookie. - The collected information consists of the following:

- -

The IP address from which you access the web site;
The type of browser and operating system you use to access our site;
The date and time you access our site;
The pages you visit; and
The addresses of pages from where you followed a link to our site.

- -

Part of this information is gathered using a tracking cookie set by the - Google Analytics service and handled by - Google as described in their - privacy policy. - See your browser documentation for instructions on how to disable the cookie if you prefer not to share - this data with Google.

- -

We use the gathered information to help us make our site more useful to visitors and to better understand how - and when our site is used. We do not track or collect personally identifiable information or associate gathered - data with any personally identifying information from other sources.

- -

By using this web site, you consent to the collection of this data in the manner and for the purpose described - above.

- - http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/79ed2d0d/src/site/xdoc/quickstart.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/quickstart.xml b/src/site/xdoc/quickstart.xml deleted file mode 100644 index cc54eab..0000000 --- a/src/site/xdoc/quickstart.xml +++ /dev/null @@ -1,208 +0,0 @@ - - - - - - Quick start - - - -

- -

First, install Apache log4php.

- -

You may also like to read the introduction chapter to familiarise - yoursef with the basic concepts used throughout the documentation and examples.

- - -

Just want logging to stdout?

- -

-include('Logger.php');
-$logger = Logger::getLogger("main");
-$logger->info("This is an informational message.");
-$logger->warn("I'm not feeling so good...");
-

- -

This produces the following output:

- -

-INFO - This is an informational message.
-WARN - I'm not feeling so good...
-

- - - - -

This example shows how to configure log4php using an XML configuration file. The framework will be - configured to log messages to a file, but only those with level greater or equal to WARN. -

- -

First, create a configuration file named config.xml containing:

- -

- -

This configuration file does the following:

- -

line 2: Creates an appender named myAppender using appender class - LoggerAppenderFile which is used for - logging to a file.
line 3: Sets the file parameter, which tells the appender to which file to - write.
line 6: Sets the root logger level to WARN. This means that logging requests - with the level lower than WARN will not be logged by the root logger.
line 7: Links myAppender to the root logger so that all events recieved by the root - logger will be forwarded to myAppender and written into the log file.

- -

To try it out, run the following code:

- -

trace("My first message.");   // Not logged because TRACE < WARN
-$log->debug("My second message.");  // Not logged because DEBUG < WARN
-$log->info("My third message.");    // Not logged because INFO < WARN
-$log->warn("My fourth message.");   // Logged because WARN >= WARN
-$log->error("My fifth message.");   // Logged because ERROR >= WARN
-$log->fatal("My sixth message.");   // Logged because FATAL >= WARN
-]]>

- -

This will create a file named myLog.log containing the following output:

- -

- - - - - -

This example covers named loggers, layouts and best practices in object-oriented programming.

- -

Create a configuration file named config.xml with the following content:

- -

- -

The configuration defines two appenders: one writes to the console, and the other to a file.

- -

The - console appender doesn't have a layout defined, so it will revert to default layout - (LoggerLayoutSimple). The - file appender uses a different layout - (LoggerLayoutPattern) - which will result in different formatting of the logging - events.

- -

The console appender is linked to the root logger. The file appender is linked to the logger named - Foo, however Foo also inherits appenders from the root logger (in this case - the console appender). This means that logging events sent to the Foo logger will be - logged both to the console and the file.

- -

Consider the following code snippet:

- -

log = Logger::getLogger(__CLASS__);
-    }
-
-    /** Logger can be used from any member method. */
-    public function go()
-    {
-        $this->log->info("We have liftoff.");
-    }
-}
-
-$foo = new Foo();
-$foo->go();
-]]>

- -

This produces the following output in the console:

INFO - We have liftoff.

- -

And the following in the log file:

01/06/11 18:43:39,545 [5428] INFO Foo - We have liftoff.

- -

Note the different layout, this is because LoggerLayoutTTCC was used as layout for the file appender.

- - -

- - http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/79ed2d0d/src/test/config/phpunit_to_surefire.xslt ---------------------------------------------------------------------- diff --git a/src/test/config/phpunit_to_surefire.xslt b/src/test/config/phpunit_to_surefire.xslt deleted file mode 100644 index 1f8fd61..0000000 --- a/src/test/config/phpunit_to_surefire.xslt +++ /dev/null @@ -1,38 +0,0 @@ - - - - - . - - - - - - - - - - - - - - - - http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/79ed2d0d/src/test/php/LoggerAppenderPoolTest.php ---------------------------------------------------------------------- diff --git a/src/test/php/LoggerAppenderPoolTest.php b/src/test/php/LoggerAppenderPoolTest.php deleted file mode 100644 index 89aecff..0000000 --- a/src/test/php/LoggerAppenderPoolTest.php +++ /dev/null @@ -1,65 +0,0 @@ -appenderMock = $this->getMock('LoggerAppenderConsole', array(), array(), '', false); - } - - /** - * @expectedException PHPUnit_Framework_Error - * @expectedExceptionMessage log4php: Cannot add unnamed appender to pool. - */ - public function testAppenderHasNoName() { - $this->appenderMock->expects($this->once()) - ->method('getName') - ->will($this->returnValue('')); - - LoggerAppenderPool::add($this->appenderMock); - } - - /** - * @expectedException PHPUnit_Framework_Error - * @expectedExceptionMessage log4php: Appender [foo] already exists in pool. Overwriting existing appender. - */ - public function testAppenderIsAdded() { - $this->appenderMock->expects($this->any()) - ->method('getName') - ->will($this->returnValue('foo')); - - LoggerAppenderPool::add($this->appenderMock); - LoggerAppenderPool::add($this->appenderMock); - - $expected = 1; - $actual = count(LoggerAppenderPool::getAppenders()); - $this->assertEquals($expected, $actual); - } -}