You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by ih...@apache.org on 2011/10/20 08:53:50 UTC
svn commit: r1186629 [5/5] - in /logging/log4php/trunk/src/site: ./ apt/
apt/docs/ apt/docs/appender/ resources/css/ resources/images/
resources/images/logos/ resources/js/ xdoc/ xdoc/docs/ xdoc/docs/appenders/
xdoc/docs/layouts/
Added: logging/log4php/trunk/src/site/xdoc/docs/filters.xml
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/xdoc/docs/filters.xml?rev=1186629&view=auto
==============================================================================
--- logging/log4php/trunk/src/site/xdoc/docs/filters.xml (added)
+++ logging/log4php/trunk/src/site/xdoc/docs/filters.xml Thu Oct 20 06:53:49 2011
@@ -0,0 +1,317 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+
+ <properties>
+ <title>Filters</title>
+ </properties>
+
+ <body>
+ <section name="Filters">
+
+ <p>Filtering is a mechanism which allows the user to configure more precisely which logging events will be
+ logged by an appender, and which will be ignored.</p>
+
+ <p>Multiple filters can be defined on any appender; they will form a filter chain. When a logging event is
+ passed onto an appender, the event will first pass through the filter chain. Each filter in the chain will
+ examine the logging event and make a decision to either:</p>
+
+ <ol type="a">
+ <li><strong>ACCEPT</strong> the logging event - The event will be logged without consulting the
+ remaining filters in the chain.</li>
+ <li><strong>DENY</strong> the logging event - The event will be not logged without consulting the
+ remaining filters in the chain.</li>
+ <li>Remain <strong>NEUTRAL</strong> - No decision is made, therefore the next filter in the chain is
+ consulted. If there are no remaining filters in the chain, the event is logged.</li>
+ </ol>
+
+ <subsection name="Configuring">
+
+ <p>Filters are configurable in the XML and PHP configuration format. They cannot be configured using
+ the properties configuration format.</p>
+
+ <p>Like appenders and layouts, depending on the class used, filters may have configurable parameters
+ which determine their behaviour.</p>
+
+ <p>Here is an XML configuration example:</p>
+
+<pre class="prettyprint linenums"><![CDATA[
+<configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="defualt" class="LoggerAppenderEcho">
+ <layout class="LoggerLayoutSimple"/>
+ <filter class="LoggerFilterStringMatch">
+ <param name="stringToMatch" value="interesting" />
+ <param name="acceptOnMatch" value="true" />
+ </filter>
+ <filter class="LoggerFilterLevelRange">
+ <param name="levelMin" value="debug" />
+ <param name="levelMax" value="error" />
+ </filter>
+ </appender>
+ <root>
+ <level value="TRACE" />
+ <appender_ref ref="defualt" />
+ </root>
+</configuration>
+]]></pre>
+
+ <p>And the same configuration in PHP format:</p>
+
+<pre class="prettyprint linenums"><![CDATA[
+array(
+ 'appenders' => array(
+ 'default' => array(
+ 'class' => 'LoggerAppenderEcho'
+ 'layout' => array(
+ 'class' => 'LoggerLayoutSimple'
+ ),
+ 'filters' => array(
+ array(
+ 'class' => 'LoggerFilterStringMatch',
+ 'params' => array(
+ 'stringToMatch' => 'interesting',
+ 'acceptOnMatch' => true,
+ )
+ ),
+ array(
+ 'class' => 'LoggerFilterLevelRange',
+ 'params' => array(
+ 'levelMin' => 'debug',
+ 'levelMax' => 'error',
+ )
+ )
+ )
+ )
+ ),
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ )
+)
+]]></pre>
+
+
+ <p>In this example, there are two filters defined for the <em>default</em> appender.</p>
+
+ <p>The first filter <code>LoggerFilterStringMatch</code> searches for the string "interesting" in the
+ logging event's message. If the string is found, the filter will ACCEPT the logging event, and the
+ event will be logged. If the string is not found, the filter will remain NEUTRAL, and the event will be
+ passed on to the next filter.</p>
+
+ <p>The second filter <code>LoggerFilterLevelRange</code> ACCEPTS all events which have a level between
+ DEBUG and ERROR (in other words, levels DEBUG, INFO, WARN and ERROR). It DENIES all other events.</p>
+
+ <p>Therefore, this filter configuration will log events which which have a level between DEBUG and
+ ERROR, except of theose which have the string "interesting" in the message. Those will be logged
+ regardless of their level.</p>
+
+ </subsection>
+
+ <subsection name="Filter reference">
+
+ <p>The following filters are available in log4php:</p>
+
+ <table>
+ <thead>
+ <tr>
+ <th>Name</th>
+ <th>Destination</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><a href="#LoggerFilterDenyAll">LoggerFilterDenyAll</a></td>
+ <td>Denies all logging events.</td>
+ </tr>
+ <tr>
+ <td><a href="#LoggerFilterLevelMatch">LoggerFilterLevelMatch</a></td>
+ <td>Filters based on logging event level.</td>
+ </tr>
+ <tr>
+ <td><a href="#LoggerFilterLevelRange">LoggerFilterLevelRange</a></td>
+ <td>Filters based on logging event level range.</td>
+ </tr>
+ <tr>
+ <td><a href="#LoggerFilterStringMatch">LoggerFilterStringMatch</a></td>
+ <td>Filters by searching for a string in the logging event message.</td>
+ </tr>
+ </tbody>
+ </table>
+ </subsection>
+
+
+ <subsection name="LoggerFilterDenyAll" id="LoggerFilterDenyAll">
+ <p>This filters simply denies all logging events. It has no configurable parameters.</p>
+ </subsection>
+
+ <subsection name="LoggerFilterLevelMatch" id="LoggerFilterLevelMatch">
+ <p>This filter either accepts the specified logger level or denies it.</p>
+
+ <h4>Configurable options</h4>
+
+ <table>
+ <thead>
+ <tr>
+ <th>Option</th>
+ <th>Type</th>
+ <th>Required</th>
+ <th>Default</th>
+ <th>Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>levelToMatch</td>
+ <td>LoggerLevel</td>
+ <td><strong>Yes</strong></td>
+ <td>-</td>
+ <td>The level to match</td>
+ </tr>
+ <tr>
+ <td>acceptOnMatch</td>
+ <td>boolean</td>
+ <td>No</td>
+ <td>true</td>
+ <td>If true, the matching log level is accepted, denied otherwise.</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <h4>Example</h4>
+
+ <p>The following filter configuration will deny all logging events with level DEBUG. It will remain
+ neutral for others.</p>
+
+<pre class="prettyprint linenums"><![CDATA[
+<filter class="LoggerFilterLevelMatch">
+ <param name="levelToMatch" value="debug" />
+ <param name="acceptOnMatch" value="false" />
+</filter>
+]]></pre>
+
+ </subsection>
+
+ <subsection name="LoggerFilterLevelRange" id="LoggerFilterLevelRange">
+ <p>This filter accepts or denies logging events if their log level is within the specified range.</p>
+
+ <h4>Configurable options</h4>
+
+ <table>
+ <thead>
+ <tr>
+ <th>Option</th>
+ <th>Type</th>
+ <th>Required</th>
+ <th>Default</th>
+ <th>Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>levelMin</td>
+ <td>LoggerLevel</td>
+ <td><strong>Yes</strong></td>
+ <td>-</td>
+ <td>The minimum level to log. If set, levels lower than this will be denied.</td>
+ </tr>
+ <tr>
+ <td>levelMax</td>
+ <td>LoggerLevel</td>
+ <td><strong>Yes</strong></td>
+ <td>-</td>
+ <td>The maximum level to log. If set, levels higher than this will be denied.</td>
+ </tr>
+ <tr>
+ <td>acceptOnMatch</td>
+ <td>boolean</td>
+ <td>No</td>
+ <td>true</td>
+ <td>If true, the matching log level is accepted, denied otherwise.</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <h4>Example</h4>
+
+ <p>The following filter configuration denies levels greater than WARN.</p>
+
+<pre class="prettyprint linenums"><![CDATA[
+<filter class="LoggerFilterLevelRange">
+ <param name="levelMax" value="warn" />
+ <param name="acceptOnMatch" value="false" />
+</filter>
+]]></pre>
+
+ </subsection>
+
+ <subsection name="LoggerFilterStringMatch" id="LoggerFilterStringMatch">
+ <p>This filter allows or denies logging events if their message contains a given string.</p>
+
+ <h4>Configurable options</h4>
+
+ <table>
+ <thead>
+ <tr>
+ <th>Option</th>
+ <th>Type</th>
+ <th>Required</th>
+ <th>Default</th>
+ <th>Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>stringToMatch</td>
+ <td>LoggerLevel</td>
+ <td><strong>Yes</strong></td>
+ <td>-</td>
+ <td>The level to match</td>
+ </tr>
+ <tr>
+ <td>levelMax</td>
+ <td>LoggerLevel</td>
+ <td><strong>Yes</strong></td>
+ <td>-</td>
+ <td>The level to match</td>
+ </tr>
+ <tr>
+ <td>acceptOnMatch</td>
+ <td>boolean</td>
+ <td>No</td>
+ <td>true</td>
+ <td>If true, the matching log level is accepted, denied otherwise.</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <h4>Example</h4>
+
+ <p>The following filter configuration denies events which contain the string "not-interesting" in
+ their message.</p>
+
+<pre class="prettyprint linenums"><![CDATA[
+<filter class="LoggerFilterStringMatch">
+ <param name="StringToMatch" value="not-interesting" />
+ <param name="AcceptOnMatch" value="false" />
+</filter>
+]]></pre>
+
+ </subsection>
+ </section>
+ </body>
+</document>
Added: logging/log4php/trunk/src/site/xdoc/docs/introduction.xml
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/xdoc/docs/introduction.xml?rev=1186629&view=auto
==============================================================================
--- logging/log4php/trunk/src/site/xdoc/docs/introduction.xml (added)
+++ logging/log4php/trunk/src/site/xdoc/docs/introduction.xml Thu Oct 20 06:53:49 2011
@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+
+ <properties>
+ <title>Introduction</title>
+ </properties>
+
+ <body>
+ <section name="Introduction">
+
+ <p>There are three main concepts in Apache log4php: loggers, appenders and layouts. These three types of
+ components work together to enable developers to log messages according to message type and level, and to
+ control at runtime how these messages are formatted and where they are reported.</p>
+
+ <subsection name="Loggers" id="Loggers">
+ <p>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.</p>
+ </subsection>
+
+ <subsection name="Appenders" id="Appenders">
+ <p>Logging requests can be sent to multiple destinations and such destinations are called appenders.
+ Appenders exist for console, files, syslog, database, sockets and other output destinations. One or
+ more appenders can be attached to a logger. Each enabled logging request for a given logger will be
+ forwarded to all the appenders in that logger.</p>
+ </subsection>
+
+ <subsection name="Layouts" id="Layouts">
+ <p>Layouts are components responsible for transforming a logging event into a string. Most appender
+ classes require a layout class to convert the event to a string so that it can be logged.</p>
+ </subsection>
+ </section>
+
+ <section name="Levels" id ="Levels">
+ <p>A level describes the severity of a logging message. There are six levels, show here in descending order
+ of severity.</p>
+
+ <table>
+ <tr>
+ <th>Level</th>
+ <th>Severity</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>FATAL</td>
+ <td>Highest</td>
+ <td>Very severe error events that will presumably lead the application to abort.</td>
+ </tr>
+ <tr>
+ <td>ERROR</td>
+ <td>...</td>
+ <td>Error events that might still allow the application to continue running.</td>
+ </tr>
+ <tr>
+ <td>WARN</td>
+ <td>...</td>
+ <td>Potentially harmful situations which still allow the application to continue running.</td>
+ </tr>
+ <tr>
+ <td>INFO</td>
+ <td>...</td>
+ <td>Informational messages that highlight the progress of the application at coarse-grained level.</td>
+ </tr>
+ <tr>
+ <td>DEBUG</td>
+ <td>...</td>
+ <td>Fine-grained informational events that are most useful to debug an application.</td>
+ </tr>
+ <tr>
+ <td>TRACE</td>
+ <td>Lowest</td>
+ <td>Finest-grained informational events.</td>
+ </tr>
+ </table>
+ </section>
+ </body>
+</document>
Added: logging/log4php/trunk/src/site/xdoc/docs/layouts/html.xml
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/xdoc/docs/layouts/html.xml?rev=1186629&view=auto
==============================================================================
--- logging/log4php/trunk/src/site/xdoc/docs/layouts/html.xml (added)
+++ logging/log4php/trunk/src/site/xdoc/docs/layouts/html.xml Thu Oct 20 06:53:49 2011
@@ -0,0 +1,165 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+
+ <properties>
+ <title>LoggerLayoutHTML</title>
+ </properties>
+
+ <body>
+ <section name="LoggerLayoutHTML" id="LoggerLayoutHTML">
+
+ <p>LoggerLayoutHTML formats the log as an HTML document.</p>
+
+ <subsection name="Options">
+ <p>The following options are available:</p>
+
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Type</th>
+ <th>Required</th>
+ <th>Default</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>locationInfo</td>
+ <td>boolean</td>
+ <td>No</td>
+ <td>false</td>
+ <td>If set to true, adds the file name and line number at which the log statement originated.</td>
+ </tr>
+ <tr>
+ <td>title</td>
+ <td>string</td>
+ <td>No</td>
+ <td>Log4php Log Messages</td>
+ <td>Sets the <![CDATA[<title>]]> of the generated HTML document.</td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ <subsection name="Examples">
+
+ <p>Configuration:</p>
+
+<pre class="prettyprint"><![CDATA[
+<configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderEcho">
+ <layout class="LoggerLayoutHtml">
+ <param name="locationInfo" value="true" />
+ </layout>
+ </appender>
+ <root>
+ <appender_ref ref="default" />
+ </root>
+</configuration>]]></pre>
+
+ <p>Running the following code:</p>
+
+<pre class="prettyprint linenums">
+Logger::configure("layout_xml.xml");
+$log = Logger::getRootLogger();
+$log->debug("Hello World!");
+$log->info("Hello World!");</pre>
+
+ <p>Produces the output as a HTML table:</p>
+
+ <table>
+ <tr>
+ <th>Time</th>
+ <th>Thread</th>
+ <th>Level</th>
+ <th>Category</th>
+ <th>File:Line</th>
+ <th>Message</th>
+ </tr>
+
+ <tr>
+ <td>0</td>
+ <td title="5868 thread">5868</td>
+ <td title="Level"><font color="#339933">DEBUG</font></td>
+ <td title="root category">root</td>
+ <td>D:\Projects\apache\log4php-config-adapters\src\examples\php\layout_html.php:23</td>
+ <td title="Message">Hello World!</td>
+ </tr>
+
+ <tr>
+ <td>2</td>
+ <td title="5868 thread">5868</td>
+ <td title="Level">INFO</td>
+ <td title="root category">root</td>
+ <td>D:\Projects\apache\log4php-config-adapters\src\examples\php\layout_html.php:24</td>
+ <td title="Message">Hello World!</td>
+ </tr>
+ </table>
+
+ <p>Source of the output:</p>
+
+<pre class="prettyprint"><![CDATA[
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+ <title>Log4php Log Messages</title>
+ <style type="text/css">
+ <!--
+ body, table {font-family: arial,sans-serif; font-size: x-small;}
+ th {background: #336699; color: #FFFFFF; text-align: left;}
+ -->
+ </style>
+</head>
+<body bgcolor="#FFFFFF" topmargin="6" leftmargin="6">
+<hr size="1" noshade>
+Log session start time 09/22/11 13:19:23<br>
+<br>
+<table cellspacing="0" cellpadding="4" border="1" bordercolor="#224466" width="100%">
+ <tr>
+ <th>Time</th>
+ <th>Thread</th>
+ <th>Level</th>
+ <th>Category</th>
+ <th>File:Line</th>
+ <th>Message</th>
+ </tr>
+ <tr>
+ <td>0</td>
+ <td title="5868 thread">5868</td>
+ <td title="Level"><font color="#339933">DEBUG</font></td>
+ <td title="root category">root</td>
+ <td>D:\Projects\apache\log4php-config-adapters\src\examples\php\layout_html.php:23</td>
+ <td title="Message">Hello World!</td>
+ </tr>
+ <tr>
+ <td>2</td>
+ <td title="5868 thread">5868</td>
+ <td title="Level">INFO</td>
+ <td title="root category">root</td>
+ <td>D:\Projects\apache\log4php-config-adapters\src\examples\php\layout_html.php:24</td>
+ <td title="Message">Hello World!</td>
+ </tr>
+</table>
+<br>
+</body>
+</html>]]></pre>
+
+ </subsection>
+ </section>
+ </body>
+</document>
Added: logging/log4php/trunk/src/site/xdoc/docs/layouts/pattern.xml
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/xdoc/docs/layouts/pattern.xml?rev=1186629&view=auto
==============================================================================
--- logging/log4php/trunk/src/site/xdoc/docs/layouts/pattern.xml (added)
+++ logging/log4php/trunk/src/site/xdoc/docs/layouts/pattern.xml Thu Oct 20 06:53:49 2011
@@ -0,0 +1,308 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+
+ <properties>
+ <title>LoggerLayoutPattern</title>
+ </properties>
+
+ <body>
+ <section name="LoggerLayoutPattern">
+
+ <p>LoggerLayoutPattern is a flexible layout configurable via a conversion pattern.</p>
+
+ <subsection name="Options">
+ <p>The following options are available:</p>
+
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Type</th>
+ <th>Required</th>
+ <th>Default</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>conversionPattern</td>
+ <td>string</td>
+ <td>No</td>
+ <td>%m%n</td>
+ <td>String which controls the output. See full specification below.</td>
+ </tr>
+ </table>
+
+ <h4>Conversion patterns</h4>
+
+ <p>This is the string which controls formatting and consists of a mix of literal content and
+ conversion specifiers.</p>
+
+ <p>The conversion pattern is closely related to the conversion pattern of the
+ <a href="http://www.cplusplus.com/reference/clibrary/cstdio/printf" target="_blank">printf</a>
+ 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.</p>
+
+ <p>Each conversion specifier starts with a percent sign (%) and is followed by optional <em>
+ format modifiers</em> and a <em>conversion character</em>. The recognized conversion specifiers
+ are:</p>
+
+ <table>
+ <tr>
+ <th>Conversion character</th>
+ <th>Converts to</th>
+ </tr>
+ <tr>
+ <td>
+ <p><code>%c</code></p>
+ <p><code>%c{<![CDATA[<precision>]]>}</code></p>
+ </td>
+ <td>
+ <p>Name of the Logger object which recieved the logging request.</p>
+
+ <p>Optionally, it can be can followed by <em>precision specifier</em>, 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.</p>
+
+ <p>For example, if the logger is named <code>foo.bar.Baz</code>, then <code>%c</code>
+ will be translated to the full logger name, <code>%c{2}</code> will be translated to
+ <code>bar.Baz</code>, and <code>%c{1}</code> will be translated to <code>Baz</code>.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><code>%C</code></p>
+ <p><code>%C{<![CDATA[<precision>]]>}</code></p>
+ </td>
+ <td>
+ <p>The fully qualified class name of the caller issuing the logging request. Currently,
+ this will always return "Logger".</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p><code>%d</code></p>
+ <p><code>%d{<![CDATA[<format>]]>}</code></p>
+ </td>
+ <td>
+ <p>The date of the logging event.</p>
+
+ <p>Optionally, may be followed by a <em>date format specifier</em> enclosed between
+ braces. The format specifier follows the PHP
+ <a href="http://php.net/manual/en/function.date.php">date</a> function. If no date
+ format specifier is given then ISO8601 format is assumed (Y-m-d H:i:s,u). </p>
+
+ <p>For example: <code>%d{Y-m-d H:i:s}</code></p>
+ </td>
+ </tr>
+ <tr>
+ <td><code>%F</code></td>
+ <td>Name of the file from which the logging request was issued.</td>
+ </tr>
+ <tr>
+ <td><code>%l</code></td>
+ <td>
+ <p>Location information of the caller which generated the logging event.</p>
+ <p>Identical to <code>%C.%M(%F:%L)</code></p>
+ </td>
+ </tr>
+ <tr>
+ <td><code>%L</code></td>
+ <td>The line number at which the logging request was issued.</td>
+ </tr>
+ <tr>
+ <td><code>%m</code></td>
+ <td>The message associated with the logging event.</td>
+ </tr>
+ <tr>
+ <td><code>%n</code></td>
+ <td>
+ <p>A platform dependent line-break character(s).</p>
+ <p>Note that a line break will not be printed unless explicitely specified.</p>
+ </td>
+ </tr>
+ <tr>
+ <td><code>%M</code></td>
+ <td>The method or function name from which the logging request was issued.</td>
+ </tr>
+ <tr>
+ <td><code>%p</code></td>
+ <td>The level of the logging event.</td>
+ </tr>
+ <tr>
+ <td><code>%r</code></td>
+ <td>The number of milliseconds elapsed since the start of the application until the creation of the logging event.</td>
+ </tr>
+ <tr>
+ <td><code>%t</code></td>
+ <td>The ID of the process that generated the logging event.</td>
+ </tr>
+ <tr>
+ <td><code>%x</code></td>
+ <td>The NDC (Nested Diagnostic Context) associated with the thread that generated the logging event.</td>
+ </tr>
+ <tr>
+ <td><code>%X{<![CDATA[<key>]]>}</code></td>
+ <td>
+ <p>The MDC (Mapped Diagnostic Context) associated with the thread that generated the
+ logging event.</p>
+ <p>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.</p>
+ </td>
+ </tr>
+ <tr>
+ <td><code>%%</code></td>
+ <td>A single percent sign.</td>
+ </tr>
+ </table>
+ </subsection>
+
+ <subsection name="Format modifiers">
+ <p>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.
+ </p>
+
+ <p>All format modifiers are optional, and are placed between the percent sign and the conversion
+ character.</p>
+
+ <p>The first format modifier is the <em>left justification flag</em> which is just the minus (-)
+ character.</p>
+
+ <p>Then comes the <em>>minimum field width</em> 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. </p>
+
+ <p>This behavior can be changed using the <em>maximum field width</em> 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. </p>
+
+ <p>The following table demonstrates various uses of format modifiers:</p>
+
+ <table>
+ <tr>
+ <th>Format modifier</th>
+ <th>Justification</th>
+ <th>Minimum width</th>
+ <th>Maximum width</th>
+ <th>Comment</th>
+ </tr>
+ <tr>
+ <td align="center"><code>%c</code></td>
+ <td align="center">none</td>
+ <td align="center">none</td>
+ <td align="center">none</td>
+ <td>Output the logger name as-is.</td>
+ </tr>
+ <tr>
+ <td align="center"><code>%20c</code></td>
+ <td align="center">right</td>
+ <td align="center">20</td>
+ <td align="center">none</td>
+ <td>Left pad with spaces if the logger name is less than 20 characters long.</td>
+ </tr>
+ <tr>
+ <td align="center"><code>%-20c</code></td>
+ <td align="center">left</td>
+ <td align="center">20</td>
+ <td align="center">none</td>
+ <td>Right pad with spaces if the logger name is less than 20 characters long.</td>
+ </tr>
+ <tr>
+ <td align="center"><code>%.30c</code></td>
+ <td align="center">none</td>
+ <td align="center">none</td>
+ <td align="center">30</td>
+ <td>Truncate from the beginning if the logger name is longer than 30 characters.</td>
+ </tr>
+ <tr>
+ <td align="center"><code>%20.30c</code></td>
+ <td align="center">right</td>
+ <td align="center">20</td>
+ <td align="center">30</td>
+ <td>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.</td>
+ </tr>
+ <tr>
+ <td align="center"><code>%-20.30c</code></td>
+ <td align="center">true</td>
+ <td align="center">20</td>
+ <td align="center">30</td>
+ <td>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.</td>
+ </tr>
+ </table>
+
+ </subsection>
+
+
+ <subsection name="Examples">
+
+ <p>The following configuration configures a <code>LoggerAppenderEcho</code> which uses the pattern
+ layout. All examples will use the same code and configuration, only the conversion pattern will
+ change.</p>
+
+ <p>Save the configuration to a file called <code>layout_pattern.xml</code>.</p>
+
+<pre class="prettyprint"><![CDATA[
+<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>
+]]></pre>
+
+ <p>Run the following code:</p>
+
+<pre class="prettyprint">
+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.");
+</pre>
+
+ <h4>Pattern example</h4>
+ <p>Conversion pattern: <code>%d %c %-5p %m%n</code></p>
+
+ <p>Produces the following output:</p>
+
+<pre>
+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.
+</pre>
+
+ <p>In this example, <code>%d</code> produces the event datetime in default format
+ (<code>Y-m-d H:i:s,u</code>), and <code>%-5p</code> 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.</p>
+ </subsection>
+ </section>
+ </body>
+</document>
Added: logging/log4php/trunk/src/site/xdoc/docs/layouts/simple.xml
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/xdoc/docs/layouts/simple.xml?rev=1186629&view=auto
==============================================================================
--- logging/log4php/trunk/src/site/xdoc/docs/layouts/simple.xml (added)
+++ logging/log4php/trunk/src/site/xdoc/docs/layouts/simple.xml Thu Oct 20 06:53:49 2011
@@ -0,0 +1,75 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+
+ <properties>
+ <title>LoggerLayoutSimple</title>
+ </properties>
+
+ <body>
+ <section name="LoggerLayoutSimple">
+
+ <p><code>LoggerLayoutSimple</code> is a basic layout which outputs only the level followed by the message.</p>
+
+ <p>It is interesting to note that the output of <code>LoggerLayoutSimple</code> is identical to that of
+ <code><a href="pattern.html">LoggerLayoutPattern</a></code> with the <em>conversion pattern</em> set to
+ <code>%p - %m%n</code>.</p>
+
+
+ <subsection name="Options">
+ <p>This layout does not have any configurable options.</p>
+ </subsection>
+
+ <subsection name="Examples">
+
+ <p>Configuration:</p>
+
+<pre class="prettyprint"><![CDATA[
+<configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderEcho">
+ <layout class="LoggerLayoutSimple" />
+ </appender>
+ <root>
+ <appender_ref ref="default" />
+ </root>
+</configuration>
+]]></pre>
+
+ <p>Running the following code:</p>
+
+<pre class="prettyprint linenums">
+Logger::configure("layout_xml.xml");
+$log = Logger::getRootLogger();
+$log->info("My first message.");
+$log->debug("My second message.");
+$log->warn("My third message.");
+</pre>
+
+ <p>Produces the following output:</p>
+
+<pre class="prettyprint"><![CDATA[
+INFO - My first message.
+DEBUG - My second message.
+WARN - My third message.
+]]></pre>
+
+ </subsection>
+ </section>
+ </body>
+</document>
Added: logging/log4php/trunk/src/site/xdoc/docs/layouts/ttcc.xml
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/xdoc/docs/layouts/ttcc.xml?rev=1186629&view=auto
==============================================================================
--- logging/log4php/trunk/src/site/xdoc/docs/layouts/ttcc.xml (added)
+++ logging/log4php/trunk/src/site/xdoc/docs/layouts/ttcc.xml Thu Oct 20 06:53:49 2011
@@ -0,0 +1,133 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+
+ <properties>
+ <title>LoggerLayoutTTCC</title>
+ </properties>
+
+ <body>
+ <section name="LoggerLayoutTTCC">
+
+ <p>The TTCC layout format was taken from Apache log4j, and originally consisted of Time, Thread, Category
+ and nested diagnostic Context information, hence the name.</p>
+
+ <p><code>LoggerLayoutTTCC</code> contains equivalent information:</p>
+ <ul>
+ <li>Time</li>
+ <li>Process ID</li>
+ <li>Logger name</li>
+ <li>Nested diagnostic context</li>
+ </ul>
+
+ <p>Output of <code>LoggerLayoutTTCC</code> is identical to that of
+ <code><a href="pattern.html">LoggerLayoutPattern</a></code> with the <em>conversion pattern</em> set to
+ <code>%d{m/d/y H:i:s,u} [%t] %p %c %x - %m%n</code>.</p>
+
+ <subsection name="Options">
+
+ <p>The following options are available:</p>
+
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Type</th>
+ <th>Required</th>
+ <th>Default</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>threadPrinting</td>
+ <td>boolean</td>
+ <td>No</td>
+ <td>true</td>
+ <td>If set to true, the process ID will be included in output.</td>
+ </tr>
+ <tr>
+ <td>categoryPrefixing</td>
+ <td>boolean</td>
+ <td>No</td>
+ <td>true</td>
+ <td>If set to true, the logger name will be included in output.</td>
+ </tr>
+ <tr>
+ <td>contextPrinting</td>
+ <td>boolean</td>
+ <td>No</td>
+ <td>true</td>
+ <td>If set to true, the nested diagnostic context will be included in output.</td>
+ </tr>
+ <tr>
+ <td>microSecondsPrinting</td>
+ <td>boolean</td>
+ <td>No</td>
+ <td>true</td>
+ <td>If set to true, the microseconds will be included in output.</td>
+ </tr>
+ <tr>
+ <td>microSecondsPrinting</td>
+ <td>string</td>
+ <td>No</td>
+ <td>%c</td>
+ <td>Overrides the date format, using the format used in PHP
+ <code>
+ <a class="externalLink" target="_blank" href="http://php.net/manual/en/function.strftime.php">strftime()</a>
+ </code> function.</td>
+ </tr>
+
+ </table>
+ </subsection>
+
+ <subsection name="Examples">
+
+ <p>Configuration:</p>
+
+<pre class="prettyprint"><![CDATA[
+<configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderEcho">
+ <layout class="LoggerLayoutTTCC" />
+ </appender>
+ <root>
+ <appender_ref ref="default" />
+ </root>
+</configuration>
+]]></pre>
+
+ <p>Running the following code:</p>
+
+<pre class="prettyprint linenums">
+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.");
+</pre>
+
+ <p>Produces the following output:</p>
+
+<pre class="prettyprint"><![CDATA[
+INFO - My first message.
+DEBUG - My second message.
+WARN - My third message.
+]]></pre>
+
+ </subsection>
+ </section>
+ </body>
+</document>
Added: logging/log4php/trunk/src/site/xdoc/docs/layouts/xml.xml
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/xdoc/docs/layouts/xml.xml?rev=1186629&view=auto
==============================================================================
--- logging/log4php/trunk/src/site/xdoc/docs/layouts/xml.xml (added)
+++ logging/log4php/trunk/src/site/xdoc/docs/layouts/xml.xml Thu Oct 20 06:53:49 2011
@@ -0,0 +1,157 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+
+ <properties>
+ <title>LoggerLayoutXml</title>
+ </properties>
+
+ <body>
+ <section name="LoggerLayoutXml">
+
+ <p><code>LoggerLayoutXml</code> formats the messages as an XML document.</p>
+
+ <subsection name="Options" id="Options">
+ <p>The following options are available:</p>
+
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Type</th>
+ <th>Required</th>
+ <th>Default</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>locationInfo</td>
+ <td>boolean</td>
+ <td>No</td>
+ <td>true</td>
+ <td>If set to true, adds the file name and line number at which the log statement originated.</td>
+ </tr>
+ <tr>
+ <td>log4jNamespace</td>
+ <td>boolean</td>
+ <td>No</td>
+ <td>false</td>
+ <td>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.</td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ <subsection name="Examples">
+
+ <h4>Default configuration example</h4>
+
+ <p>The default configuration of <code>LoggerLayoutXml</code> will use the log4php XML namespace and
+ include the location information.</p>
+
+ <p>Configuration file:</p>
+
+<pre class="prettyprint"><![CDATA[
+<configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderEcho">
+ <layout class="LoggerLayoutXml" />
+ </appender>
+ <root>
+ <appender_ref ref="default" />
+ </root>
+</configuration>
+]]></pre>
+
+ <p>Running the following code:</p>
+
+<pre class="prettyprint linenums">
+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.");
+</pre>
+
+ <p>Produces the following output:</p>
+
+<pre class="prettyprint"><![CDATA[
+<log4php:eventSet xmlns:log4php="http://logging.apache.org/log4php/" version="0.3" includesLocationInfo="true">
+
+<log4php:event logger="myLogger" level="INFO" thread="4464" timestamp="1317215164482">
+<log4php:message><![CDATA[Lorem ipsum dolor sit amet, consectetur adipiscing elit.]]]]><![CDATA[>]]><![CDATA[</log4php:message>
+<log4php:locationInfo class="main" file="D:\Temp\log4php\layout_pattern.php" line="5" method="main" />
+</log4php:event>
+
+<log4php:event logger="myLogger" level="DEBUG" thread="4464" timestamp="1317215164513">
+<log4php:message><![CDATA[Donec a diam lectus.]]]]><![CDATA[>]]><![CDATA[</log4php:message>
+<log4php:locationInfo class="main" file="D:\Temp\log4php\layout_pattern.php" line="6" method="main" />
+</log4php:event>
+
+<log4php:event logger="myLogger" level="WARN" thread="4464" timestamp="1317215164514">
+<log4php:message><![CDATA[Sed sit amet ipsum mauris.]]]]><![CDATA[>]]><![CDATA[</log4php:message>
+<log4php:locationInfo class="main" file="D:\Temp\log4php\layout_pattern.php" line="7" method="main" />
+</log4php:event>
+
+</log4php:eventSet>
+]]></pre>
+
+
+ <h4>Overriding default options</h4>
+
+ <p>This example show how to configure <code>LoggerLayoutXml</code> to exclude the location information
+ and use the log4j XML namespace.</p>
+
+ <p>Configuration file:</p>
+
+<pre class="prettyprint"><![CDATA[
+<configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderEcho">
+ <layout class="LoggerLayoutXml">
+ <param name="locationInfo" value="false" />
+ <param name="log4jNamespace" value="true" />
+ </layout>
+ </appender>
+ <root>
+ <appender_ref ref="default" />
+ </root>
+</configuration>
+]]></pre>
+ <p>Using this configuration will produce the following output:</p>
+
+<pre class="prettyprint"><![CDATA[
+<log4j:eventSet xmlns:log4j="http://jakarta.apache.org/log4j/" version="0.3" includesLocationInfo="false">
+<log4j:event logger="myLogger" level="INFO" thread="3156" timestamp="1317216571470">
+<log4j:message><![CDATA[Lorem ipsum dolor sit amet, consectetur adipiscing elit.]]]]><![CDATA[>]]><![CDATA[</log4j:message>
+</log4j:event>
+
+<log4j:event logger="myLogger" level="DEBUG" thread="3156" timestamp="1317216571471">
+<log4j:message><![CDATA[Donec a diam lectus.]]]]><![CDATA[>]]><![CDATA[</log4j:message>
+</log4j:event>
+
+<log4j:event logger="myLogger" level="WARN" thread="3156" timestamp="1317216571471">
+<log4j:message><![CDATA[Sed sit amet ipsum mauris.]]]]><![CDATA[>]]><![CDATA[</log4j:message>
+</log4j:event>
+
+</log4j:eventSet>
+]]></pre>
+
+ </subsection>
+ </section>
+ </body>
+</document>
Added: logging/log4php/trunk/src/site/xdoc/docs/loggers.xml
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/xdoc/docs/loggers.xml?rev=1186629&view=auto
==============================================================================
--- logging/log4php/trunk/src/site/xdoc/docs/loggers.xml (added)
+++ logging/log4php/trunk/src/site/xdoc/docs/loggers.xml Thu Oct 20 06:53:49 2011
@@ -0,0 +1,289 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+
+ <properties>
+ <title>Loggers</title>
+ </properties>
+
+ <body>
+ <section name="Loggers">
+
+ <p>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.</p>
+
+ <p>Creating a logger is done by calling the static <code>getLogger()</code> method on the Logger object
+ and providing the name of the logger. For example, to create a logger named <code>foo</code>:</p>
+
+ <pre class="prettyprint">$logger = Logger::getLogger('foo');</pre>
+
+ <p>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 <code>info()</code> creates a logging request of level
+ <code>INFO</code>. For example:</p>
+
+ <pre class="prettyprint">$logger->info("This is the message to be logged.");</pre>
+
+ <p>Loggers by themselves do not define where these messages will be logged. For that you need to assign
+ one or more <a href="./appender.html">appenders</a> to the logger.</p>
+
+ <subsection name="Logger threshold" id="Logger_threshold">
+ <p>A logger can be assigned a threshold level. All logging requests with level lower than this threshold
+ will be ignored.</p>
+
+ <p>For example, setting logger threshold to <code>INFO</code> means that logging requests with levels
+ <code>TRACE</code> and <code>DEBUG</code> will not be logged by this logger.</p>
+
+ <p>An example of setting the root logger threshold to <code>DEBUG</code>:</p>
+
+<pre class="prettyprint"><![CDATA[
+<configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderConsole" />
+ <root>
+ <level value="debug" />
+ <appender_ref ref="default" />
+ </root>
+</configuration>
+]]></pre>
+
+ <p>By default loggers do not have a threshold set, which means they will log all events, regardless of the
+ level.</p>
+ </subsection>
+
+ <subsection name="Configuring loggers" id="Configuring_loggers">
+ <p>Loggers can be individually configured in the configuration file. </p>
+
+ <p>The simplest example is to configure the root logger, since all other loggers will inherit its
+ settings, as explained in the <a href="#Logger_hierarchy">next section</a>.</p>
+
+<pre class="prettyprint"><![CDATA[
+<configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderConsole" />
+ <root>
+ <level value="debug" />
+ <appender_ref ref="default" />
+ </root>
+</configuration>
+]]></pre>
+ <p>This configuration adds the <code>default</code> appender to the root logger, and sets it's
+ <a href="#Logger_threshold">threshold level</a> to DEBUG.</p>
+
+ <p>It is also possible to configure individual named loggers. For example, let's configure the
+ <code>foo</code> logger, used in the example above, and set it's threshold to WARN:</p>
+
+<pre class="prettyprint"><![CDATA[
+<configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderConsole" />
+ <logger name="foo">
+ <level value="warn" />
+ <appender_ref ref="default" />
+ </logger>
+</configuration>
+]]></pre>
+ </subsection>
+
+ <subsection name="Logger hierarchy" id="Logger_hierarchy">
+ <p>Loggers follow a parent-child relationship pattern which is implemented by using a naming pattern.
+ A logger is said to be an <em>ancestor</em> of another logger if its name followed by a dot is a
+ prefix of the <em>descendant</em> logger name. A logger is said to be a <em>parent</em> of a
+ <em>child</em> logger if there are no ancestors between itself and the descendant logger.</p>
+
+ <p>For example, the logger named <code>foo</code> is a parent of the logger named <code>foo.bar</code>.
+ Similarly, <code>org</code> is a parent of <code>org.apache</code> and an ancestor of
+ <code>org.apache.logging</code>. This naming scheme should be familiar to most developers.</p>
+
+ <p>The root logger resides at the top of the logger hierarchy. It is exceptional in two ways:</p>
+ <ul>
+ <li>it always exists,</li>
+ <li>it cannot be retrieved by name.</li>
+ </ul>
+
+ <p>Invoking the class static <code>Logger::getRootLogger()</code> method retrieves the root logger.
+ All other loggers are instantiated and retrieved with the <code>Logger::getLogger($name)</code>
+ 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.</p>
+ </subsection>
+
+ <subsection name="Logger inheritance" id="Logger_inheritance">
+ <p>The threshold level and appenders are inherited from the parent to the child loggers.</p>
+
+ <p>For example examine the following configuration:</p>
+
+<pre class="prettyprint"><![CDATA[
+<configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderConsole" />
+ <root>
+ <level value="debug" />
+ <appender_ref ref="default" />
+ </root>
+</configuration>
+]]></pre>
+
+ <p>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.</p>
+
+<pre class="prettyprint"><![CDATA[
+$main = Logger::getLogger('main');
+$main->trace('This will not be logged.');
+$main->info('This will be logged.');
+]]></pre>
+ <p>A logger named <code>main</code> 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:</p>
+
+ <pre>INFO - This will be logged.</pre>
+ </subsection>
+
+ <subsection name="Appender additivity" id="Appender_additivity">
+ <p>Appender additivity is a property of loggers to inherit their parent's appenders. By default all
+ loggers have appender additivity enabled.</p>
+
+ <p>Let's take the following example:</p>
+
+<pre class="prettyprint"><![CDATA[
+<configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="A1" class="LoggerAppenderConsole" />
+ <appender name="A2" class="LoggerAppenderConsole" />
+ <root>
+ <appender_ref ref="A1" />
+ </root>
+ <logger name="foo">
+ <appender_ref ref="A2" />
+ </logger>
+</configuration>
+]]></pre>
+ <p>Since additivity is enabled by default, the logger <code>foo</code> will have two linked appenders:
+ A1 which it will inherit from the root logger, and A2 which is defined for it specifically.</p>
+
+ <p>Therefore, by executing the following code:</p>
+
+<pre class="prettyprint"><![CDATA[
+$main = Logger::getLogger('foo');
+$main->info('This will be logged twice.');
+]]></pre>
+ <p>The message will be logged twice - once by A1 and once by A2, producing:</p>
+
+<pre>
+INFO - This will be logged twice.
+INFO - This will be logged twice.
+</pre>
+
+ <h4>Disabling appender additivity</h4>
+
+ <p>Logger's appender additivity can also be disabled if needed.</p>
+
+ <p>If the <code>foo</code> logger in the previous example was configured like this:</p>
+
+<pre class="prettyprint"><![CDATA[
+<logger name="foo" additivity="false">
+ <appender_ref ref="A2" />
+</logger>
+]]></pre>
+ <p>Then the logger would not have inherited the A1 appender from the root logger, and the message
+ would have been logged only once.</p>
+
+ <h4>A more complex example</h4>
+
+ <p>In this example we will look at multiple loggers making a hierarchy.</p>
+
+ <p>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.</p>
+
+ <p>Let's take the following configuration file:</p>
+
+<pre class="prettyprint"><![CDATA[
+<configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="A1" class="LoggerAppenderConsole" />
+ <appender name="A2" class="LoggerAppenderConsole" />
+ <appender name="A3" class="LoggerAppenderConsole" />
+ <appender name="A4" class="LoggerAppenderConsole" />
+
+ <root>
+ <appender_ref ref="A1" />
+ </root>
+ <logger name="foo">
+ <appender_ref ref="A2" />
+ <appender_ref ref="A3" />
+ </logger>
+ <logger name="foo.bar" />
+ <logger name="foo.bar.baz" additivity="false">
+ <appender_ref ref="A4" />
+ </logger>
+</configuration>
+]]></pre>
+ <p>The table below shows how the configuration is interpreted, and which appenders are inherited:</p>
+
+ <table>
+ <thead>
+ <tr>
+ <th>Logger name</th>
+ <th>Linked appenders</th>
+ <th>Additivity flag</th>
+ <th>Output targets</th>
+ <th>Comment</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>root</td>
+ <td>A1</td>
+ <td>N/A</td>
+ <td>A1</td>
+ <td>One appender, named A1, is added to root logger. Any logging requests to root logger
+ will be forwarded only to that one appender.</td>
+ </tr>
+ <tr>
+ <td>foo</td>
+ <td>A2, A3</td>
+ <td>true</td>
+ <td>A1, A2, A3</td>
+ <td>A logger named <code>foo</code> is created and two appenders, named A2 and A3, are
+ added to it. Additionally, because of logger additivity, <code>foo</code> 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.</td>
+ </tr>
+ <tr>
+ <td>foo.bar</td>
+ <td>none</td>
+ <td>true</td>
+ <td>A1, A2, A3</td>
+ <td>A logger named <code>foo.bar</code> is created. Because it's name starts with
+ <code>foo</code>, it will be created as a child of the <code>foo</code> logger.
+ No appenders are added to <code>foo.bar</code> but it will inherit it's ancestor's
+ appenders: appenders A2 and A3 from <code>foo</code> and A1 from <code>root</code>.
+ Logging requests to this logger will be forwarded to appenders A1, A2 and A3.</td>
+ </tr>
+ <tr>
+ <td>foo.bar.baz</td>
+ <td>A4</td>
+ <td>false</td>
+ <td>A4</td>
+ <td>Finally, logger <code>foo.bar.baz</code> is created, and because of it's name it is
+ created as child to <code>foo.bar</code>. One appender, A4 is added to it. However, since
+ it's additivity flag is set to <em>false</em>, it will not inherit any appenders from it's
+ ancestors. Logging requests to this logger will be forwarded only to appender A4.</td>
+ </tr>
+ </tbody>
+
+ </table>
+ </subsection>
+ </section>
+ </body>
+</document>
Added: logging/log4php/trunk/src/site/xdoc/docs/renderers.xml
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/xdoc/docs/renderers.xml?rev=1186629&view=auto
==============================================================================
--- logging/log4php/trunk/src/site/xdoc/docs/renderers.xml (added)
+++ logging/log4php/trunk/src/site/xdoc/docs/renderers.xml Thu Oct 20 06:53:49 2011
@@ -0,0 +1,137 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+
+ <properties>
+ <title>Renderers</title>
+ </properties>
+
+ <body>
+ <section name="Renderers">
+ <p>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
+ <em>renderer</em>.</p>
+
+ <subsection name="Default renderer">
+
+ <p>For example, let's say that an application uses a Person object, like this one:</p>
+
+<pre class="prettyprint linenums"><![CDATA[
+class Person {
+ public $firstName;
+ public $lastName;
+ public $age;
+}
+]]></pre>
+
+ <p>If you try logging it:</p>
+
+<pre class="prettyprint linenums"><![CDATA[
+$person = new Person();
+$person->firstName = 'John';
+$person->lastName = 'Doe';
+$person->age = 37;
+
+$logger = Logger::getLogger('main');
+$logger->info("Here comes the person:");
+$logger->info($person);
+]]></pre>
+ <p>Log4php will render it using the default renderer and you will end the output will look something
+ like:</p>
+
+<pre class="prettyprint linenums"><![CDATA[
+INFO - Here comes the person:
+INFO - Person::__set_state(array(
+ 'firstName' => 'John',
+ 'lastName' => 'Doe',
+ 'age' => 37,
+))
+]]></pre>
+
+ </subsection>
+
+ <subsection name="Creating a custom renderer">
+ <p>In order to make log4php render our Person object in a more readable format, we need to create a
+ custom renderer class which will convert Person objects to a string suitable for logging.</p>
+
+ <p>Let's call our renderer class PersonRenderer.</p>
+
+<pre class="prettyprint linenums"><![CDATA[
+/** All object renderers must implement the LoggerRendererObject interface. */
+class PersonRenderer implements LoggerRendererObject {
+ public function render($person) {
+ return "{$person->firstName} {$person->lastName} ({$person->age})";
+ }
+}
+]]></pre>
+
+ <p>Now log4php has to be configured to use PersonRenderer for rendering Person objects. This is done
+ in the configuration file.</p>
+
+ <p>XML configuration:</p>
+
+<pre class="prettyprint linenums"><![CDATA[
+<configuration xmlns="http://logging.apache.org/log4php/">
+ <renderer renderedClass="Person" renderingClass="PersonRenderer" />
+ <appender name="defualt" class="LoggerAppenderEcho" />
+ <root>
+ <appender_ref ref="defualt" />
+ </root>
+</configuration>
+]]></pre>
+
+ <p>Equivalent PHP configuration:</p>
+
+<pre class="prettyprint linenums"><![CDATA[
+array(
+ 'renderers' => array(
+ 'renderedClass' => 'Person',
+ 'renderingClass' => 'PersonRenderer'
+ ),
+ 'appenders' => array(
+ 'default' => array(
+ 'class' => 'LoggerAppenderEcho',
+ ),
+ ),
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ ),
+);
+]]></pre>
+
+ <p>If the same code is run as above, the following output is produced:</p>
+
+<pre class="prettyprint linenums"><![CDATA[
+INFO - Here comes the person:
+INFO - John Doe (37)
+]]></pre>
+ <p>Which is much more readable than the default rendering.</p>
+ </subsection>
+
+ <subsection name="Class hierarchy">
+ <p>Object rendering follows the class hierarchy. </p>
+
+ <p>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.</p>
+ </subsection>
+ </section>
+ </body>
+</document>
Added: logging/log4php/trunk/src/site/xdoc/install.xml
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/xdoc/install.xml?rev=1186629&view=auto
==============================================================================
--- logging/log4php/trunk/src/site/xdoc/install.xml (added)
+++ logging/log4php/trunk/src/site/xdoc/install.xml Thu Oct 20 06:53:49 2011
@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+
+ <properties>
+ <title>Installing</title>
+ </properties>
+
+ <body>
+ <section name="Installing">
+
+ <subsection name="From source package">
+
+ <p>Download the latest source package from the <a href="download.html">download page</a> and unpack it.</p>
+
+ <p>The package directory structure is as follows:</p>
+
+<pre>
+ââââ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
+</pre>
+ <p>Most users will primarily be interested in the source code which is located in
+ <code>/src/main/php</code>. The contents of this directory may be copied to a directory within your
+ project for easier access.</p>
+
+ </subsection>
+
+ <subsection name="From PEAR repository">
+
+ <p>Apache log4php has it's own <a href="http://pear.apache.org/log4php/index.html">PEAR channel</a>.</p>
+
+ <p>To install from the PEAR channel, execute the following commands:</p>
+
+<pre>
+pear channel-discover pear.apache.org/log4php
+pear install log4php/Apache_log4php
+</pre>
+
+ </subsection>
+ </section>
+ </body>
+</document>
Added: logging/log4php/trunk/src/site/xdoc/privacy.xml
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/xdoc/privacy.xml?rev=1186629&view=auto
==============================================================================
--- logging/log4php/trunk/src/site/xdoc/privacy.xml (added)
+++ logging/log4php/trunk/src/site/xdoc/privacy.xml Thu Oct 20 06:53:49 2011
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+
+ <properties>
+ <title>Privacy policy</title>
+ </properties>
+
+ <body>
+ <section name="Privacy policy">
+ <p>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:</p>
+
+ <ul>
+ <li>The IP address from which you access the web site;</li>
+ <li>The type of browser and operating system you use to access our site;</li>
+ <li>The date and time you access our site;</li>
+ <li>The pages you visit; and</li>
+ <li>The addresses of pages from where you followed a link to our site.</li>
+ </ul>
+
+ <p>Part of this information is gathered using a tracking cookie set by the
+ <a href="http://www.google.com/analytics" class="externalLink" target="_blank">Google Analytics</a> service
+ and handled by Google as described in their
+ <a href="http://www.google.com/privacy.html" class="externalLink" target="_blank">privacy policy</a>.
+ See your browser documentation for instructions on how to disable the cookie if you prefer not to share
+ this data with Google.</p>
+
+ <p>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.</p>
+
+ <p>By using this web site, you consent to the collection of this data in the manner and for the purpose described
+ above.</p>
+ </section>
+ </body>
+</document>
Added: logging/log4php/trunk/src/site/xdoc/quickstart.xml
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/xdoc/quickstart.xml?rev=1186629&view=auto
==============================================================================
--- logging/log4php/trunk/src/site/xdoc/quickstart.xml (added)
+++ logging/log4php/trunk/src/site/xdoc/quickstart.xml Thu Oct 20 06:53:49 2011
@@ -0,0 +1,205 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+
+ <properties>
+ <title>Quick start</title>
+ </properties>
+
+ <body>
+ <section name="Quick start">
+
+ <p>First, <a href="install.html">install Apache log4php</a>.</p>
+
+ <p>You may also like to read the <a href="docs/introduction.html">introduction chapter</a> to familiarise
+ yoursef with the basic concepts used throughout the documentation and examples.</p>
+
+ <subsection name="A trivial example">
+ <p>Just want logging to stdout?</p>
+
+<pre class="prettyprint linenums">
+include('log4php/Logger.php');
+$logger = Logger::getLogger("main");
+$logger->info("foo");
+$logger->warn("bar");
+</pre>
+
+ <p>This produces the following output:</p>
+
+<pre>
+Sun Jul 26 01:40:23 2009,021 [10093] INFO main - foo
+Sun Jul 26 01:40:23 2009,030 [10093] WARN main - bar
+</pre>
+
+ </subsection>
+
+ <subsection name="A simple example">
+ <p>This example demonstrates how to log messages to a file, but only with level greater or equal to
+ WARN.</p>
+
+ <p>Create a configuration file named <code>log4php.xml</code> containing:</p>
+
+<pre class="prettyprint linenums"><![CDATA[
+<configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="myAppender" class="LoggerAppenderFile">
+ <param name="file" value="myLog.log" />
+ </appender>
+ <root>
+ <level value="WARN" />
+ <appender_ref ref="myAppender" />
+ </root>
+</configuration>
+]]></pre>
+
+ <p>This configuration file:</p>
+
+ <ul>
+ <li>Creates an appender named <code>myAppender</code> using appender class <code>
+ <a href="docs/appenders.html#LoggerAppenderFile">LoggerAppenderFile</a></code> which is used for
+ logging to a file (on line 2).</li>
+
+ <li>Sets the <code>file</code> parameter, which is required for LoggerAppenderFile, to the path
+ to the file in which events will be logged (on line 3).</li>
+
+ <li>Sets the root logger level to <code>WARN</code> (on line 6)). This means that logging requests
+ with the level lower than WARN will be ignored.</li>
+
+ <li>Links <code>myAppender</code> to the root logger (on line 7) so that all events recieved by the root
+ logger will be forwarded to <code>myAppender</code> and written into the log file.</li>
+ </ul>
+
+ <p>To try it out, run the following code:</p>
+
+<pre class="prettyprint linenums"><![CDATA[
+// Insert the path where you unpacked log4php
+include('log4php/Logger.php');
+
+// Tell log4php to use our configuration file.
+Logger::configure('log4php.xml');
+
+// Fetch a logger, it will inherit settings from the root logger
+$log = Logger::getLogger('myLogger');
+
+// Start logging
+$log->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
+]]></pre>
+
+ <p>This will create a file named <code>myLog.log</code> containing the following output:</p>
+
+<pre><![CDATA[
+WARN - My fourth message.
+ERROR - My fifth message.
+FATAL - My sixth message.
+]]></pre>
+ </subsection>
+
+ <subsection name="An advanced example">
+
+ <p>This example covers named loggers, layouts and best practices in object-oriented programming.</p>
+
+ <p>Create a configuration file named <code>log4php.xml</code> with the following content:</p>
+
+<pre class="prettyprint linenums"><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<configuration xmlns="http://logging.apache.org/log4php/">
+
+ <appender name="myConsoleAppender" class="LoggerAppenderConsole" />
+
+ <appender name="myFileAppender" class="LoggerAppenderFile">
+ <layout class="LoggerLayoutTTCC" />
+ <param name="file" value="myLog.log" />
+ </appender>
+
+ <logger name="Foo">
+ <appender_ref ref="myFileAppender" />
+ </logger>
+
+ <root>
+ <level value="DEBUG" />
+ <appender_ref ref="myConsoleAppender" />
+ </root>
+</configuration>
+]]></pre>
+
+ <p>The configuration defines two appenders: one writes to the console, and the other to a file.</p>
+
+ <p>The
+ console appender doesn't have a layout defined, so it will revert to default layout
+ (<code><a href="docs/layouts/simple.html">LoggerLayoutSimple</a></code>). The
+ file appender uses a different layout
+ (<code><a href="docs/layouts/ttcc.html">LoggerLayoutTTCC</a></code>)
+ which will result in different formatting of the logging
+ events.</p>
+
+ <p>The console appender is linked to the root logger. The file appender is linked to the logger named
+ <code>Foo</code>, however <code>Foo</code> also inherits appenders from the root logger (in this case
+ the console appender). This means that logging events sent to the <code>Foo</code> logger will be
+ logged both to the console and the file.</p>
+
+ <p>Consider the following code snippet:</p>
+
+<pre class="prettyprint linenums"><![CDATA[
+// Include and configure log4php
+include('log4php/Logger.php');
+Logger::configure('log4php.xml');
+
+/**
+ * This is a classic usage pattern: one logger object per class.
+ */
+class Foo
+{
+ /** Holds the Logger. */
+ private $log;
+
+ /** Logger is instantiated in the constructor. */
+ public function __construct()
+ {
+ // The __CLASS__ constant holds the class name, in our case "Foo".
+ // Therefore this creates a logger named "Foo" (which we configured in the config file)
+ $this->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();
+]]></pre>
+
+ <p>This produces the following output in the console:</p>
+ <pre>INFO - We have liftoff.</pre>
+
+ <p>And the following in the log file:</p>
+ <pre>01/06/11 18:43:39,545 [5428] INFO Foo - We have liftoff.</pre>
+
+ <p>Note the different layout, this is because LoggerLayoutTTCC was used as layout for the file appender.</p>
+ </subsection>
+
+ </section>
+ </body>
+</document>