blob: 110fef82f499cf633121d9e112972f8c1838d302 [file] [log] [blame]
~~ 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.
------
Quickstart
------
------
------
Quickstart
First, please {{{./download.html}download Apache log4php}} and unpack it.
Optionally, you may copy the folder <<src/main/php>>, which contains the source code, to a location of your choosing. For example, a folder within your project.
Please read the {{{./docs/introduction.html}introduction}} to familiarise yoursef with the basic concepts used throughout the documentation and examples.
* A trivial example
You just want logging to stdout?
+--
include('log4php/Logger.php');
$logger = Logger::getLogger("main");
$logger->info("foo");
$logger->warn("bar");
+--
This gives:
+--
Sun Jul 26 01:40:23 2009,021 [10093] INFO main - foo
Sun Jul 26 01:40:23 2009,030 [10093] WARN main - bar
+--
* A simple example
Wish to log all events to a file, but only those level is greater or equal to WARN?
First, create a configuration file named log4php.xml containing:
+--
<?xml version="1.0" encoding="UTF-8"?>
<log4php:configuration xmlns:log4php="http://logging.apache.org/log4php/">
<appender name="myAppender" class="LoggerAppenderFile"> <!-- 1 -->
<param name="file" value="myLog.log" /> <!-- 2 -->
</appender>
<root>
<level value="WARN" /> <!-- 3 -->
<appender_ref ref="myAppender" /> <!-- 4 -->
</root>
</log4php:configuration>
+--
This configuration file does the following:
[[1]] Creates an appender called <myAppender> using appender class {{{./docs/appender/appender.html#LoggerAppenderFile}LoggerAppenderFile}} which is used for logging to a file.
[[2]] Sets the <file> parameter, which is required for LoggerAppenderFile, to the path to the file in which events will be logged.
[[3]] Configures the root {{{./docs/loggers.html}logger}} at WARN {{{./docs/introduction.html#Levels}level}}. Therefore, logging requests with the level lower than WARN will be ignored.
[[4]] Links <myAppender> with 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:
+--
// 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
+--
This will create a file named <<myLog.log>> containing the following:
+--
WARN - My fourth message.
ERROR - My fifth message.
FATAL - My sixth message.
+--
* An advanced example
This example covers:
* named loggers
* using layouts
* best practices in object-oriented programming
[]
Create the following configuration file:
+--
<?xml version="1.0" encoding="UTF-8"?>
<log4php:configuration xmlns:log4php="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>
</log4php:configuration>
+--
Note that:
* Two appenders are created. The first logs to the console, and the second to a file. The file appender uses a different layout, 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> will also inherit appenders from the root logger (the console appender in this case). In other words, logging events sent to a logger named <Foo> will be logged both to the console and the file.
[]
The code:
+--
include('log4php/Logger.php');
Logger::configure('D:\Projects\apache\_playground\log4php.xml');
/**
* This is a classic pattern: using 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();
+--
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.