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