<?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('Logger.php'); | |
$logger = Logger::getLogger("main"); | |
$logger->info("This is an informational message."); | |
$logger->warn("I'm not feeling so good..."); | |
</pre> | |
<p>This produces the following output:</p> | |
<pre> | |
INFO - This is an informational message. | |
WARN - I'm not feeling so good... | |
</pre> | |
</subsection> | |
<subsection name="A simple example"> | |
<p>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 <code>WARN</code>. | |
</p> | |
<p>First, create a configuration file named <code>config.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 does the following:</p> | |
<ul> | |
<li><em>line 2</em>: Creates an appender named <code>myAppender</code> using appender class <code> | |
<a href="docs/appenders/file.html">LoggerAppenderFile</a></code> which is used for | |
logging to a file.</li> | |
<li><em>line 3</em>: Sets the <code>file</code> parameter, which tells the appender to which file to | |
write.</li> | |
<li><em>line 6</em>: Sets the root logger level to <code>WARN</code>. This means that logging requests | |
with the level lower than <code>WARN</code> will not be logged by the root logger.</li> | |
<li><em>line 7</em>: Links <code>myAppender</code> to the root logger 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('config.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>config.xml</code> with the following content:</p> | |
<pre class="prettyprint linenums"><![CDATA[ | |
<configuration xmlns="http://logging.apache.org/log4php/"> | |
<appender name="myConsoleAppender" class="LoggerAppenderConsole" /> | |
<appender name="myFileAppender" class="LoggerAppenderFile"> | |
<layout class="LoggerLayoutPattern"> | |
<param name="conversionPattern" value="%date [%logger] %message%newline" /> | |
</layout> | |
<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/pattern.html">LoggerLayoutPattern</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('config.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> |