Author: grobmeier
Date: Mon Jul 27 05:58:01 2009
New Revision: 798031
URL: http://svn.apache.org/viewvc?rev=798031&view=rev
Log:
LOG4PHP-60: patch applied from Christian Hammers. Improved quickstart.apt.
Applied with slight modifications (apt formatting issues)
Modified:
incubator/log4php/trunk/src/changes/changes.xml
incubator/log4php/trunk/src/site/apt/quickstart.apt
Modified: incubator/log4php/trunk/src/changes/changes.xml
URL:
http://svn.apache.org/viewvc/incubator/log4php/trunk/src/changes/changes.xml?rev=798031&r1=798030&r2=798031&view=diff
==============================================================================
--- incubator/log4php/trunk/src/changes/changes.xml (original)
+++ incubator/log4php/trunk/src/changes/changes.xml Mon Jul 27 05:58:01 2009
@@ -60,6 +60,7 @@
<action type="update" issue="LOG4PHP-52">Use of custom factorys
is discouraged - clean up (Christian Grobmeier)</action>
<action type="update" issue="LOG4PHP-53">Removed references
were appropriate (Christian Grobmeier)</action>
<action type="fix" issue="LOG4PHP-54">PHPDoc is wrong due to
class movements - clean up (Christian Grobmeier)</action>
+ <action type="update" issue="LOG4PHP-60">Improved
quickstart.apt (Christian Hammers)</action>
<action type="update">Initial port to PHP 5 (Knut
Urdalen)</action>
<action type="update">Established new unit test suite (Knut
Urdalen)</action>
<action type="update">Added a range of examples (Knut
Urdalen)</action>
Modified: incubator/log4php/trunk/src/site/apt/quickstart.apt
URL:
http://svn.apache.org/viewvc/incubator/log4php/trunk/src/site/apt/quickstart.apt?rev=798031&r1=798030&r2=798031&view=diff
==============================================================================
--- incubator/log4php/trunk/src/site/apt/quickstart.apt (original)
+++ incubator/log4php/trunk/src/site/apt/quickstart.apt Mon Jul 27 05:58:01 2009
@@ -22,66 +22,97 @@
First, please {{{install.html}install Log4PHP}}.
- Then create an configuration file which can be a standard property file
(.ini), an XML file
- or an PHP array. Log4PHP makes it possible to log several packages with
different configurations.
- In the examples directory are several examples available.
-
- Here is an simple property configuration:
-
-+--
-log4php.appender.default = LoggerAppenderEcho
-log4php.appender.default.layout = LoggerLayoutSimple
-log4php.additivity.mylogger= "false"
-log4php.logger.mylogger = INFO, default
-log4php.rootLogger = WARN, default
-+--
+* Overview
- This configures the so called root logger at WARN level with the default
appender. An additional
- Logger named "mylogger" is configured at INFO level.
+ The log4* framework is quite flexible, e.g. you can have a all log messages
of
+ a certain importance go to one big logfile, all warnings from the database
+ classes send via e-mail and all everything, even debug output from some other
+ class going to a separate file. The configuration can be done using a
standard
+ property file (.ini), an XML file or an PHP array.
+
+ Before we start explaining how to configure it, we first explain some terms
+ that are used all over the documentation:
- Once you have created such a file, you need to define it's location by
setting a constant:
-
-+--
- define('LOG4PHP_CONFIGURATION', 'resources/myconfig.properties');
-+--
-
- Log4PHP will look up the configuration file and prepare the framework for
logging.
+ * logger - an object of the Logger class that's used like
"$logger->info("foo");".
+ Each logger has a name like "main" or "myclass".
+
+ * hierarchy - logger names can be separated by dots like "myclass" and
"myclass.database"
+ to form some kind of hierarchy. Since Log4PHP uses property inheritance,
subpackages of
+ "myclass.database" could be configured differently from "myclass" while
still inherit
+ their ancestors configuration options per default.
- Since log4php makes use of date functions, it is recommended that you have
set:
- date_default_timezone_set(); somewhere within your application.
+ * appender - defines if the output goes to a file, a database table, e-mail,
syslog etc.
-+--
- date_default_timezone_set('Europe/London');
+ * layout - defines how the output looks like e.g. just "INFO: foo bar" or
with timestamps, logger name, PID etc.
+
+** A trivial example
+ You just want logging to stdout?
+
+--
+ define('LOG4PHP_CONFIGURATOR_CLASS', 'LoggerConfiguratorBasic');
+ require_once('log4php/LoggerManager.php');
- You are now able to do logging in your application. Let's take a look at
this class:
+ $logger = LoggerManager::getLogger("main");
+ $logger->info("foo");
+ $logger->warn("bar");
++--
+
+ This gives:
+--
-class MyClass {
- private $logger;
-
- public function __construct() {
- $this->logger = LoggerManager::getLogger('mylogger');
- $this->logger->info('Hello!');
- }
-}
+ Sun Jul 26 01:40:23 2009,021 [10093] INFO main - foo
+ Sun Jul 26 01:40:23 2009,030 [10093] WARN main - bar
+--
- The code above uses the 'mylogger' Logger we defined in our properties file.
If you would use
- a name which hasn't been defined in your config file, the root logger is
used.
-
- We recommend to separate your application logically. Maybe you would like to
have database logic
- logged another way than template logic. In that way you could use 'database'
as a loggers name
- in the configuration file. Since Log4PHP uses property inheritance,
subpackages of 'database' package
- can be configured their own way. However, we would like to recommend a name
like:
- 'database.entities.Myclass'. This way you can configure logging not only at
package level but also
- on class name level.
+** A simple example
+
+ Here is an advanced, yet still simple, log4php.properties configuration:
++--
+ log4php.appender.default = LoggerAppenderEcho
+ log4php.appender.default.layout = LoggerLayoutSimple
+
+ log4php.rootLogger = WARN, default
+
+ log4php.logger.mylogger = INFO, default
+ log4php.additivity.mylogger = "false"
++--
- Last but not least, please shutdown all loggers, appenders and whatever with:
+ This configures the so called root logger at WARN level with the default
+ appender. An additional Logger named "mylogger" is configured at INFO level.
+ If you would give one of your loggers a name which hasn't been defined, like
+ "main" in the below source, in your config file, the root logger is used.
+ Once you have created such a file, you need to define it's location by
setting
+ a constant: Log4PHP will look up the configuration file and prepare the
+ framework for logging.
+--
-LoggerManager::shutdown();
+ define('LOG4PHP_CONFIGURATION', 'log4php.properties');
+ require_once('log4php/LoggerManager.php');
+
+ class MyClass {
+ private $logger;
+
+ public function __construct() {
+ $this->logger = LoggerManager::getLogger(__CLASS__);
+ $this->logger->debug('currently in constructor');
+ }
+ }
+
+ $logger = LoggerManager::getLogger('main');
+ $logger->info('below warn and thus not printed');
+
+ new MyClass();
++--
+
+ The output looks like this. It is very brief as we used SimpleLayout and
hides
+ one message because the default treshhold is set to WARN:
+
++--
+ DEBUG - currently in constructor
+--
+
+** Hints
+ * Since log4php makes use of date functions, it is recommended that you have
set: date_default_timezone_set('Europe/Berlin'); or similar somewhere within
your application.
