logging-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ihabu...@apache.org
Subject [01/23] Initial implementation of the new manual
Date Sat, 14 Dec 2013 14:56:47 GMT
Updated Branches:
  refs/heads/develop 4e7dd2157 -> 520fdbd17


http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/layouts/html.rst
----------------------------------------------------------------------
diff --git a/docs/layouts/html.rst b/docs/layouts/html.rst
new file mode 100644
index 0000000..7ef4e98
--- /dev/null
+++ b/docs/layouts/html.rst
@@ -0,0 +1,123 @@
+================
+LoggerLayoutHTML
+================
+
+LoggerLayoutHTML formats the log as an HTML document.
+
+Parameters
+----------
+
++----------------+---------+----------+----------+-------------------------------------------------+
+| Parameter      | Type    | Required | Default  | Description                                     |
++================+=========+==========+==========+=================================================+
+| locationInfo   | boolean | No       | true     | If set to true, adds the file name and line     |
+|                |         |          |          | number at which the log statement originated.   |
++----------------+---------+----------+----------+-------------------------------------------------+
+| title          | string  | No       | Log3php  | Sets the title of the generated HTML document.  |
+|                |         |          | Log      |                                                 |
+|                |         |          | Messages |                                                 |
++----------------+---------+----------+----------+-------------------------------------------------+
+
+Examples
+--------
+
+.. container:: tabs
+
+    .. rubric:: XML format
+    .. code-block:: xml
+
+        <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>
+
+    .. rubric:: PHP format
+    .. code-block:: php
+
+        array(
+            'appenders' => array(
+                'default' => array(
+                    'class' => 'LoggerAppenderEcho',
+                    'layout' => array(
+                        'class' => 'LoggerLayoutHtml',
+                    )
+                )
+            ),
+            'rootLogger' => array(
+                'appenders' => array('default')
+            ),
+        )
+
+Running the following code:
+
+.. code-block:: php
+
+    Logger::configure("layout_xml.xml");
+    $log = Logger::getRootLogger();
+    $log->debug("Hello World!");
+    $log->info("Hello World!");
+
+Produces the output as a HTML table:
+
++------+--------+-------+----------+--------------------------------+--------------+
+| Time | Thread | Level | Category | File\:Line                     | Message      |
++======+========+=======+==========+================================+==============+
+| 0    | 5868   | DEBUG | root     | /tmp/log4php/layout_html.php:3 | Hello world! |
++------+--------+-------+----------+--------------------------------+--------------+
+| 2    | 5868   | INFO  | root     | /tmp/log4php/layout_html.php:4 | Hello world! |
++------+--------+-------+----------+--------------------------------+--------------+
+
+Source of the output:
+
+.. code-block:: html
+
+    <!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>

http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/layouts/index.rst
----------------------------------------------------------------------
diff --git a/docs/layouts/index.rst b/docs/layouts/index.rst
new file mode 100644
index 0000000..deaa978
--- /dev/null
+++ b/docs/layouts/index.rst
@@ -0,0 +1,24 @@
+=======
+Layouts
+=======
+
+Layouts are components responsible for transforming a logging event into a 
+string. 
+
+More often than not, users wish to customize not only the output destination but 
+also the output format. This is accomplished by associating a layout with an 
+appender. All messages logged by that appender will use the given layout. 
+
+
+Layout reference
+================
+
+.. toctree::
+   :maxdepth: 1
+
+   html
+   pattern
+   serialized
+   simple
+   ttcc
+   xml

http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/layouts/pattern.rst
----------------------------------------------------------------------
diff --git a/docs/layouts/pattern.rst b/docs/layouts/pattern.rst
new file mode 100644
index 0000000..3c10c9b
--- /dev/null
+++ b/docs/layouts/pattern.rst
@@ -0,0 +1,498 @@
+===================
+LoggerLayoutPattern
+===================
+
+LoggerLayoutPattern is a flexible layout configurable via a conversion pattern.
+
+Parameters
+==========
+
+The following parameters are available:
+
++-------------------+---------+----------+------------------+------------------------------------+
+| Parameter         | Type    | Required | Default          | Description                        |
++===================+=========+==========+==================+====================================+
+| conversionPattern | boolean | No       | %message%newline | String which controls the output.  |
+|                   |         |          |                  | See full specification below.      |
++-------------------+---------+----------+------------------+------------------------------------+
+
+.. list-table::
+   :widths: 20 10 10 20 40
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Required
+     - Default
+     - Description
+   * - conversionPattern
+     - boolean
+     - No
+     - %message%newline
+     - String which controls the output. See full specification below.
+
+Conversion patterns
+===================
+
+**Conversion pattern** is a string which controls the formatting of logging
+events. It controls how logging events will be transformed into strings by the
+layout.
+
+The conversion pattern is closely related to the conversion pattern of the PHP
+`sprintf <http://www.php.net/manual/en/function.sprintf.php>`_ function. It is
+composed of literal text and format control expressions called *conversion
+specifiers*.
+
+A conversion specifier begins with a percent sign (%) and is followed by a
+*conversion word*. Some conversion words require one or more *options* to be
+given. These are specified in braces after the conversion word. An example of a
+conversion specifier is ``%message`` which will be converted into the message
+from the logging event which is being logged.
+
+
+
+Conversion specifiers
+---------------------
+
+.. function:: %c{length}
+.. function:: %lo{length}
+.. function:: %logger{length}
+
+    Name of the Logger which generated the logging request.
+
+    Optionally, a desired output length can be specified. If given, the
+    converter will attempt to abbreviate the logger name without losing too much
+    information in the process. If zero length is specified, only the rightmost
+    name fragment will be output.
+
+    Specifying the desired length 0 means that only the class name will be
+    returned without the corresponding namespace.
+
+    Several examples of the shortening algorithm in action:
+
+    .. list-table::
+       :header-rows: 1
+
+       * - Conversion specifier
+         - Logger name
+         - Result
+       * - ``%logger``
+         - org\\apache\\logging\\log4php\\Foo
+         - org\\apache\\logging\\log4php\\Foo
+       * - ``%logger{0}``
+         - org\\apache\\logging\\log4php\\Foo
+         - Foo
+       * - ``%logger{10}``
+         - org\\apache\\logging\\log4php\\Foo
+         - o\\a\\l\\l\\Foo
+       * - ``%logger{20}``
+         - org\\apache\\logging\\log4php\\Foo
+         - o\\a\\l\\log4php\\Foo
+       * - ``%logger{25}``
+         - org\\apache\\logging\\log4php\\Foo
+         - o\\a\\logging\\log4php\\Foo
+       * - ``%logger{30}``
+         - org\\apache\\logging\\log4php\\Foo
+         - org\\apache\\logging\\log4php\\Foo
+
+    Note that rightmost segment will never be shortened. It is possible that the
+    resulting string will be longer than the specified desired length.
+    For backward compatibility, a dot can be used as a namespace separator, as
+    well as the backslash.
+
+.. function:: %C{length}
+.. function:: %class{length}
+
+    The fully qualified class name of the caller issuing the logging request.
+    Just like **%logger**, a desired length can be defined as an option.
+
+.. function:: %cookie{key}
+
+    A value from the $_COOKIE superglobal array corresponding to the given key.
+    If no key is given, will return all values in key=value format.
+
+.. function:: %d{pattern}
+.. function:: %date{pattern}
+
+    The date/time of the logging event. Accepts a pattern string as an option.
+    The pattern syntax is the same as used by the
+    `PHP date <http://php.net/manual/en/function.date.php>`_ function.
+
+    If no pattern is given, the date format will default to the ISO8601 datetime
+    format, which is the same as giving the pattern: ``c``.
+
+    +-------------------------------+-------------------------------------------+
+    | Conversion specifier          | Result                                    |
+    +===============================+===========================================+
+    | %d                            | 2011-12-27T12:01:32+01:00                 |
+    +-------------------------------+-------------------------------------------+
+    | %date                         | 2011-12-27T12:01:32+01:00                 |
+    +-------------------------------+-------------------------------------------+
+    | %date{ISO8601}                | 2011-12-27T12:01:32+01:00                 |
+    +-------------------------------+-------------------------------------------+
+    | %date{Y-m-d H:i:s,u}          | 2011-12-27 12:01:32,610                   |
+    +-------------------------------+-------------------------------------------+
+    | %date{l jS \of F Y h:i:s A}   | Tuesday 27th of December 2011 12:01:32 PM |
+    +-------------------------------+-------------------------------------------+
+
+.. function:: %e{key}
+.. function:: %env{key}
+
+    A value from the $_ENV superglobal array corresponding to the given key.
+
+    If no key is given, will return all values in key=value format.
+
+.. function:: %ex
+.. function:: %exception
+.. function:: %throwable
+
+    The exception associated with the logging event, along with it's stack
+    trace. If there is no exception, evalutates to an empty string.
+
+.. function:: %F
+.. function:: %file
+
+    Name of the file from which the logging request was issued.
+
+.. function:: %l
+.. function:: %location
+
+    Location information of the caller which generated the logging event.
+
+    Identical to ``%C.%M(%F:%L)``
+
+.. function:: %L
+.. function:: %line
+
+    The line number at which the logging request was issued.
+
+.. function:: %m
+.. function:: %msg
+.. function:: %message
+
+    The message associated with the logging event.
+
+.. function:: %M
+.. function:: %method
+
+    The method or function name from which the logging request was issued.
+
+.. function:: %n
+.. function:: %newline
+
+    A platform dependent line-break character(s).
+
+    Note that a line break will not be printed unless explicitely specified.
+
+.. function:: %p
+.. function:: %le
+.. function:: %level
+
+    The level of the logging event.
+
+.. function:: %r
+.. function:: %relative
+
+    The number of milliseconds elapsed since the start of the application until
+    the creation of the logging event.
+
+.. function:: %req{key}
+.. function:: %request{key}
+
+    A value from the $_REQUEST superglobal array corresponding to the given key.
+
+    If no key is given, will return all values in key=value format.
+
+.. function:: %s{key}
+.. function:: %server{key}
+
+    A value from the $_SERVER superglobal array corresponding to the given key.
+
+    If no key is given, will return all values in key=value format.
+
+.. function:: %ses{key}
+.. function:: %session{key}
+
+    A value from the $_SESSION superglobal array corresponding to the given key.
+
+    If no key is given, will return all values in key=value format.
+
+.. function:: %sid
+.. function:: %sessionid
+
+    The active session ID, or an empty string if not in session.
+
+    Equivalent to calling ``session_id()``.
+
+.. function:: %t
+.. function:: %pid
+.. function:: %process
+
+    The ID of the process that generated the logging event.
+
+.. function:: %x
+.. function:: %ndc
+
+    The NDC (Nested Diagnostic Context) associated with the thread that
+    generated the logging event.
+
+.. function:: %X{key}
+.. function:: %mdc{key}
+
+    A value from the Mapped Diagnostic Context (MDC) corresponding to the given
+    key.
+
+Format modifiers
+----------------
+
+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.
+
+Both format modifiers are optional, and are placed between the percent sign (%)
+and the conversion word. These are, in order:
+
+#. A **minimum width specifier**, a number which determines the minimum width of
+   the resulting string. If the resulting string is shorter that the given
+   number, it will be padded with spaces to the desired length. By default, the
+   string is right-justified (padded from left), but adding a "-" sign before
+   the specifier will make it left-justified.
+
+#. A **maximum widht specifier**, a dot (".") followed by a number which
+   determines the maximum allowed width of the resulting string. If the
+   resulting string is shorter than the given number, it will be truncated to
+   the maximum width. By default the string is truncated from the right, but
+   adding a "-" sign before the specifier will cause it to truncate from the
+   left.
+
+The following table demonstrates various uses of format modifiers:
+
+.. list-table::
+    :header-rows: 1
+    :widths: 10 10 10 10 10 50
+
+    * - Format modifier
+      - Padding
+      - Trimming
+      - Min. width
+      - Max. width
+      - Comment
+    * - ``%logger``
+      - none
+      - none
+      - none
+      - none
+      - Output the logger name as-is.
+    * - ``%20logger``
+      - right
+      - none
+      - 20
+      - none
+      - Left pad with spaces if the logger name is less than 20 characters long.
+    * - ``%-20logger``
+      - left
+      - none
+      - 20
+      - none
+      - Right pad with spaces if the logger name is less than 20 characters
+        long.
+    * - ``%.30logger``
+      - none
+      - right
+      - none
+      - 30
+      - Trim from the end if the logger name is longer than 30 characters.
+    * - ``%.-30logger``
+      - none
+      - left
+      - none
+      - 30
+      - Trim from the beginning if the logger name is longer than 30 characters.
+    * - ``%20.30logger``
+      - right
+      - right
+      - 20
+      - 30
+      - Left pad with spaces if the logger name is shorter than 20 characters.
+        However, if the logger name is longer than 30 characters, then trim from
+        the end.
+    * - ``%-20.30logger``
+      - left
+      - right
+      - 20
+      - 30
+      - Right pad with spaces if the logger name is shorter than 20 characters.
+        However, if the logger name is longer than 30 characters, then trim from
+        the end.
+
+The following table lists a couple of examples for using format modifiers.
+
+Note that the square brackets are only added to the conversion pattern to
+visually delimit the output.
+
++--------------------+------------------------+------------------+-------------------------------+
+| Conversion pattern | Logger name            | Result           | Note                          |
++====================+========================+==================+===============================+
+| [%10logger]        | Foo                    | ``[       Foo]`` | Added padding, right aligned. |
++--------------------+------------------------+------------------+-------------------------------+
+| [%-10logger]       | Foo                    | ``[Foo       ]`` | Added padding, left aligned.  |
++--------------------+------------------------+------------------+-------------------------------+
+| [%.10logger]       | org.apache.log4php.Foo | ``[org.apache]`` | Trimmed from right.           |
++--------------------+------------------------+------------------+-------------------------------+
+| [%.-10logger]      | org.apache.log4php.Foo | ``[og4php.Foo]`` | Trimmed from left.            |
++--------------------+------------------------+------------------+-------------------------------+
+
+Examples
+--------
+
+The following configuration configures a ``LoggerAppenderEcho`` which uses the
+pattern layout. All examples will use the same code and configuration, only the
+conversion pattern will change from example to example.
+
+.. container:: tabs
+
+    .. rubric:: XML format
+    .. code-block:: xml
+
+        <configuration xmlns="http://logging.apache.org/log4php/">
+            <appender name="default" class="LoggerAppenderEcho">
+                <layout class="LoggerLayoutPattern">
+                    <param name="conversionPattern" value="%date %logger %-5level %msg%n" />
+                </layout>
+            </appender>
+            <root>
+                <appender_ref ref="default" />
+            </root>
+        </configuration>
+
+    .. rubric:: PHP format
+    .. code-block:: php
+
+        array(
+            'appenders' => array(
+                'default' => array(
+                    'class' => 'LoggerAppenderEcho',
+                    'layout' => array(
+                        'class' => 'LoggerLayoutPattern',
+                        'params' => array(
+                            'conversionPattern' => '%date %logger %-5level %msg%n'
+                        )
+                    )
+                )
+            ),
+            'rootLogger' => array(
+                'appenders' => array('default')
+            ),
+        )
+
+Example code:
+
+.. code-block:: php
+
+    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.");
+
+A simple example
+~~~~~~~~~~~~~~~~
+
+Conversion pattern: ``%date %logger %-5level %msg%n``
+
+Running the example code produces the following output:
+
+.. code-block:: bash
+
+    2012-02-27T19:42:17+01:00 myLogger INFO  Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+    2012-02-27T19:42:17+01:00 myLogger DEBUG Donec a diam lectus.
+    2012-02-27T19:42:17+01:00 myLogger WARN  Sed sit amet ipsum mauris.
+
+In this example, ``%date`` is converted to the event datetime in default format
+(corresponding to the ISO-8601 specification), and ``%-5level`` 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.
+
+Notice that the newline between logging events (%n) has to be explicitely
+defined. Otherwise all logging events will be logged in the same line.
+
+Formatting the date
+~~~~~~~~~~~~~~~~~~~
+
+The ``%date`` conversion word can take the desired date format as an option. For
+example, if you're European, the d.m.Y date format might be more familiar. Also,
+adding milliseconds.
+
+Conversion pattern: ``%date{d.m.Y H:i:s,u} %logger %-5level %msg%n``
+
+Running the example code produces the following output:
+
+.. code-block:: bash
+
+    27.02.2012 20:14:41,624 myLogger INFO  Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+    27.02.2012 20:14:41,625 myLogger DEBUG Donec a diam lectus.
+    27.02.2012 20:14:41,626 myLogger WARN  Sed sit amet ipsum mauris.
+
+Logging HTTP requests
+~~~~~~~~~~~~~~~~~~~~~
+
+If log4php is used to log HTTP requests, a pattern like this might be useful:
+
+``%date [%pid] From:%server{REMOTE_ADDR}:%server{REMOTE_PORT} Request:[%request] Message: %msg%n``
+
+Request ``/test.php?foo=bar`` it will produce the output similar to:
+
+.. code-block:: bash
+
+    2012-01-02T14:19:33+01:00 [22924] From:194.152.205.71:11257 Request:[foo=bar] Message: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+    2012-01-02T14:19:33+01:00 [22924] From:194.152.205.71:11257 Request:[foo=bar] Message: Donec a diam lectus.
+    2012-01-02T14:19:33+01:00 [22924] From:194.152.205.71:11257 Request:[foo=bar] Message: Sed sit amet ipsum mauris.
+
+``%server{REMOTE_ADDR}`` is equivalent to PHP code ``$_SERVER['REMOTE_ADDR']``.
+
+Logging exceptions
+~~~~~~~~~~~~~~~~~~
+
+If you wish to log any exception passed to the logging methods, you should add
+the ``%ex`` specifier to the end of your conversion pattern, after ``%newline``.
+This way, if an exception is loggerd it will be addded to your log below your
+message.
+
+For example: ``%date %logger %message%newline%ex``
+
+In the following code, suppose that the work() method can throw an exception.
+This wolud be a good way to deal with it:
+
+.. code-block:: php
+
+    $log = Logger::getLogger('foo');
+    $log->info("Let's try this");
+
+    try
+    {
+        $foo = new Foo();
+        $foo->work(123);
+    }
+    catch(Exception $ex)
+    {
+        // Exception is passed as the second parameter
+        $log->error("That didn't work", $ex);
+    }
+    $log->info("Done.");
+
+If work() throws an exception, your log might look something like this:
+
+.. code-block:: bash
+
+    2012-10-08T10:11:18+02:00 foo Let's try this
+    2012-10-08T10:11:18+02:00 foo That didn't work
+    exception 'Exception' with message 'Doesn't work' in D:\work\exceptions.php:38
+    Stack trace:
+    #0 D:\work\exceptions.php(29): Bar->work(123)
+    #1 D:\work\exceptions.php(48): Foo->work(123)
+    #2 {main}
+    2012-10-08T10:11:18+02:00 foo Done.
+
+The exception, along with the full stack trace ends up in your log. This also
+works with nested exceptions, the full stack trace is added.

http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/layouts/serialized.rst
----------------------------------------------------------------------
diff --git a/docs/layouts/serialized.rst b/docs/layouts/serialized.rst
new file mode 100644
index 0000000..88b15e7
--- /dev/null
+++ b/docs/layouts/serialized.rst
@@ -0,0 +1,72 @@
+======================
+LoggerLayoutSerialized
+======================
+
+``LoggerLayoutSerialized`` formats the logging event using the PHP's
+`serialize() <http://php.net/manual/en/function.serialize.php>`_ function.
+
+Parameters
+----------
+
+The following parameters are available:
+
++--------------+---------+----------+---------+-------------------------------------------------+
+| Parameter    | Type    | Required | Default | Description                                     |
++==============+=========+==========+=========+=================================================+
+| locationInfo | boolean | No       | true    | If set to true, event's location information    |
+|              |         |          |         | will be initialized before serialization.       |
+|              |         |          |         | Enabling this parameter makes logging slower    |
+|              |         |          |         | and should be used only if required.            |
++--------------+---------+----------+---------+-------------------------------------------------+
+
+Examples
+--------
+
+.. container:: tabs
+
+    .. rubric:: XML format
+    .. code-block:: xml
+
+        <configuration xmlns="http://logging.apache.org/log4php/">
+            <appender name="default" class="LoggerAppenderEcho">
+                <layout class="LoggerLayoutSerialized" />
+            </appender>
+            <root>
+                <appender_ref ref="default" />
+            </root>
+        </configuration>
+
+    .. rubric:: PHP format
+    .. code-block:: php
+
+        array(
+            'appenders' => array(
+                'default' => array(
+                    'class' => 'LoggerAppenderEcho',
+                    'layout' => array(
+                        'class' => 'LoggerLayoutSerialized',
+                    )
+                )
+            ),
+            'rootLogger' => array(
+                'appenders' => array('default')
+            ),
+        )
+
+Running the following code:
+
+.. code-block:: php
+
+    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.");
+
+Produces the following output:
+
+.. code-block:: bash
+
+    O:18:"LoggerLoggingEvent":10:{s:24:" LoggerLoggingEvent fqcn";s:6:"Logger";s:32:" LoggerLoggingEvent categoryName";s:8:"myLogger";s:8:" * level";O:11:"LoggerLevel":3:{s:18:" LoggerLevel level";i:20000;s:21:" LoggerLevel levelStr";s:4:"INFO";s:29:" LoggerLevel syslogEquivalent";i:6;}s:23:" LoggerLoggingEvent ndc";N;s:37:" LoggerLoggingEvent ndcLookupRequired";b:1;s:27:" LoggerLoggingEvent message";s:56:"Lorem ipsum dolor sit amet, consectetur adipiscing elit.";s:35:" LoggerLoggingEvent renderedMessage";N;s:30:" LoggerLoggingEvent threadName";N;s:9:"timeStamp";d:1319380554.782227;s:32:" LoggerLoggingEvent locationInfo";N;}
+    O:18:"LoggerLoggingEvent":10:{s:24:" LoggerLoggingEvent fqcn";s:6:"Logger";s:32:" LoggerLoggingEvent categoryName";s:8:"myLogger";s:8:" * level";O:11:"LoggerLevel":3:{s:18:" LoggerLevel level";i:10000;s:21:" LoggerLevel levelStr";s:5:"DEBUG";s:29:" LoggerLevel syslogEquivalent";i:7;}s:23:" LoggerLoggingEvent ndc";N;s:37:" LoggerLoggingEvent ndcLookupRequired";b:1;s:27:" LoggerLoggingEvent message";s:20:"Donec a diam lectus.";s:35:" LoggerLoggingEvent renderedMessage";N;s:30:" LoggerLoggingEvent threadName";N;s:9:"timeStamp";d:1319380554.78247;s:32:" LoggerLoggingEvent locationInfo";N;}
+    O:18:"LoggerLoggingEvent":10:{s:24:" LoggerLoggingEvent fqcn";s:6:"Logger";s:32:" LoggerLoggingEvent categoryName";s:8:"myLogger";s:8:" * level";O:11:"LoggerLevel":3:{s:18:" LoggerLevel level";i:30000;s:21:" LoggerLevel levelStr";s:4:"WARN";s:29:" LoggerLevel syslogEquivalent";i:4;}s:23:" LoggerLoggingEvent ndc";N;s:37:" LoggerLoggingEvent ndcLookupRequired";b:1;s:27:" LoggerLoggingEvent message";s:26:"Sed sit amet ipsum mauris.";s:35:" LoggerLoggingEvent renderedMessage";N;s:30:" LoggerLoggingEvent threadName";N;s:9:"timeStamp";d:1319380554.78268;s:32:" LoggerLoggingEvent locationInfo";N;}

http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/layouts/simple.rst
----------------------------------------------------------------------
diff --git a/docs/layouts/simple.rst b/docs/layouts/simple.rst
new file mode 100644
index 0000000..4b63bd5
--- /dev/null
+++ b/docs/layouts/simple.rst
@@ -0,0 +1,71 @@
+==================
+LoggerLayoutSimple
+==================
+
+``LoggerLayoutSimple`` is a basic layout which outputs only the level followed
+by the message.
+
+It is interesting to note that the output of ``LoggerLayoutSimple`` is identical
+to that of `LoggerLayoutPattern <patern.html>`_ with the `conversion pattern` 
+set to ``%p - %m%n``.
+
+Parameters
+----------
+
+This layout does not have any configurable parameters.
+
+Examples
+--------
+
+Sample configuration:
+
+.. container:: tabs
+
+    .. rubric:: XML format
+    .. code-block:: xml
+
+        <configuration xmlns="http://logging.apache.org/log4php/">
+            <appender name="default" class="LoggerAppenderEcho">
+                <layout class="LoggerLayoutSimple" />
+            </appender>
+            <root>
+                <appender_ref ref="default" />
+            </root>
+        </configuration>
+
+    .. rubric:: PHP format
+    .. code-block:: php
+
+        array(
+            'appenders' => array(
+                'default' => array(
+                    'class' => 'LoggerAppenderEcho',
+                    'layout' => array(
+                        'class' => 'LoggerLayoutSimple',
+                    )
+                )
+            ),
+            'rootLogger' => array(
+                'appenders' => array('default')
+            ),
+        )
+
+
+
+Running the following code:
+
+.. code-block:: php
+
+    Logger::configure("layout_xml.xml");
+    $log = Logger::getRootLogger();
+    $log->info("My first message.");
+    $log->debug("My second message.");
+    $log->warn("My third message.");
+
+Produces the following output:
+
+.. code-block:: bash
+
+    INFO - My first message.
+    DEBUG - My second message.
+    WARN - My third message.

http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/layouts/ttcc.rst
----------------------------------------------------------------------
diff --git a/docs/layouts/ttcc.rst b/docs/layouts/ttcc.rst
new file mode 100644
index 0000000..0fc2a22
--- /dev/null
+++ b/docs/layouts/ttcc.rst
@@ -0,0 +1,115 @@
+================
+LoggerLayoutTTCC
+================
+
+.. warning::
+
+    LoggerLayoutTTCC is deprecated and will be removed in a future release. Please
+    use `LoggerLayoutPattern <pattern.html>`_ instead.
+
+The TTCC layout format was taken from Apache log4j, and originally consisted of
+Time, Thread, Category and nested diagnostic Context information, hence the
+name.
+
+``LoggerLayoutTTCC`` contains equivalent information:
+
+* Time
+* Process ID
+* Logger name
+* Nested diagnostic context
+
+Output of ``LoggerLayoutTTCC`` is identical to that of LoggerLayoutPattern_
+with the *conversion pattern* set to ``%d{m/d/y H:i:s,u} [%t] %p %c %x - %m%n``.
+
+Parameters
+----------
+
+The following parameters are available:
+
+
+.. list-table::
+    :widths: 20 10 10 10 50
+    :header-rows: 1
+
+    * - Parameter
+      - Type
+      - Required
+      - Default
+      - Description
+    * - threadPrinting
+      - boolean
+      - No
+      - true
+      - If set to true, the process ID will be included in output.
+    * - categoryPrefixing
+      - boolean
+      - No
+      - true
+      - If set to true, the logger name will be included in output.
+    * - contextPrinting
+      - boolean
+      - No
+      - true
+      - If set to true, the nested diagnostic context will be included in output.
+    * - microSecondsPrinting
+      - boolean
+      - No
+      - true
+      - If set to true, the microseconds will be included in output.
+
+Examples
+--------
+
+Configuration:
+
+.. container:: tabs
+
+    .. rubric:: XML format
+    .. code-block:: xml
+
+        <configuration xmlns="http://logging.apache.org/log4php/">
+            <appender name="default" class="LoggerAppenderEcho">
+                <layout class="LoggerLayoutTTCC" />
+            </appender>
+            <root>
+                <appender_ref ref="default" />
+            </root>
+        </configuration>
+
+    .. rubric:: PHP format
+    .. code-block:: php
+
+        array(
+            'appenders' => array(
+                'default' => array(
+                    'class' => 'LoggerAppenderEcho',
+                    'layout' => array(
+                        'class' => 'LoggerLayoutTTCC',
+                    )
+                )
+            ),
+            'rootLogger' => array(
+                'appenders' => array('default')
+            ),
+        )
+
+For this example, some Nested Diagnostic Context is added also. Running the
+following code:
+
+.. code-block:: php
+
+    Logger::configure("config.xml");
+    LoggerNDC::push("Some Context");
+
+    $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.");
+
+Produces the following output:
+
+.. code-block:: bash
+
+    02/20/12 23:36:39,772 [9820] INFO myLogger Some Context - Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+    02/20/12 23:36:39,773 [9820] DEBUG myLogger Some Context - Donec a diam lectus.
+    02/20/12 23:36:39,773 [9820] WARN myLogger Some Context - Sed sit amet ipsum mauris.

http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/layouts/xml.rst
----------------------------------------------------------------------
diff --git a/docs/layouts/xml.rst b/docs/layouts/xml.rst
new file mode 100644
index 0000000..d1385f2
--- /dev/null
+++ b/docs/layouts/xml.rst
@@ -0,0 +1,137 @@
+===============
+LoggerLayoutXml
+===============
+
+``LoggerLayoutXml`` formats the messages as an XML document.
+
+Parameters
+==========
+
++-----------------+---------+----------+---------+-------------------------------------------------+
+| Parameter       | Type    | Required | Default | Description                                     |
++=================+=========+==========+=========+=================================================+
+| locationInfo    | boolean | No       | true    | If set to true, adds the file name and line     |
+|                 |         |          |         | number at which the log statement originated.   |
++-----------------+---------+----------+---------+-------------------------------------------------+
+| log4jNamespace  | boolean | No       | false   | If set to true then log4j XML namespace will be |
+|                 |         |          |         | used instead of the log4php namespace. This can |
+|                 |         |          |         | be useful when using log viewers which can only |
+|                 |         |          |         | parse the log4j namespace such as Apache        |
+|                 |         |          |         | Chainsaw.                                       |
++-----------------+---------+----------+---------+-------------------------------------------------+
+
+Examples
+========
+
+Default configuration example
+-----------------------------
+
+The default configuration of ``LoggerLayoutXml`` will use the log4php XML 
+namespace and include the location information.
+
+Configuration file:
+
+.. container:: tabs
+
+    .. rubric:: XML format
+    .. code-block:: xml
+
+        <configuration xmlns="http://logging.apache.org/log4php/">
+            <appender name="default" class="LoggerAppenderEcho">
+                <layout class="LoggerLayoutXml" />
+            </appender>
+            <root>
+                <appender_ref ref="default" />
+            </root>
+        </configuration>
+
+    .. rubric:: PHP format
+    .. code-block:: php
+
+        array(
+            'appenders' => array(
+                'default' => array(
+                    'class' => 'LoggerAppenderEcho',
+                    'layout' => array(
+                        'class' => 'LoggerLayoutXml',
+                    )
+                )
+            ),
+            'rootLogger' => array(
+                'appenders' => array('default')
+            ),
+        )
+
+Running the following code:
+
+.. code-block:: php
+
+    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.");
+
+Produces the following output:
+
+.. code-block:: xml
+
+    <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>
+
+Overriding default options
+--------------------------
+
+This example show how to configure ``LoggerLayoutXml`` to exclude the location
+information and use the log4j XML namespace.
+
+Configuration file:
+
+.. code-block:: xml
+
+    <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>
+
+Using this configuration will produce the following output:
+
+.. code-block:: xml
+
+    <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>

http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/make.bat
----------------------------------------------------------------------
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 0000000..78149c8
--- /dev/null
+++ b/docs/make.bat
@@ -0,0 +1,190 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set I18NSPHINXOPTS=%SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	:help
+	echo.Please use `make ^<target^>` where ^<target^> is one of
+	echo.  html       to make standalone HTML files
+	echo.  dirhtml    to make HTML files named index.html in directories
+	echo.  singlehtml to make a single large HTML file
+	echo.  pickle     to make pickle files
+	echo.  json       to make JSON files
+	echo.  htmlhelp   to make HTML files and a HTML help project
+	echo.  qthelp     to make HTML files and a qthelp project
+	echo.  devhelp    to make HTML files and a Devhelp project
+	echo.  epub       to make an epub
+	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  text       to make text files
+	echo.  man        to make manual pages
+	echo.  texinfo    to make Texinfo files
+	echo.  gettext    to make PO message catalogs
+	echo.  changes    to make an overview over all changed/added/deprecated items
+	echo.  linkcheck  to check all external links for integrity
+	echo.  doctest    to run all doctests embedded in the documentation if enabled
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
+	goto end
+)
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "singlehtml" (
+	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Apachelog4php.qhcp
+	echo.To view the help file:
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Apachelog4php.ghc
+	goto end
+)
+
+if "%1" == "devhelp" (
+	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished.
+	goto end
+)
+
+if "%1" == "epub" (
+	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The epub file is in %BUILDDIR%/epub.
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "text" (
+	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The text files are in %BUILDDIR%/text.
+	goto end
+)
+
+if "%1" == "man" (
+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The manual pages are in %BUILDDIR%/man.
+	goto end
+)
+
+if "%1" == "texinfo" (
+	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+	goto end
+)
+
+if "%1" == "gettext" (
+	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.The overview file is in %BUILDDIR%/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+	goto end
+)
+
+:end

http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/quickstart.rst
----------------------------------------------------------------------
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
new file mode 100644
index 0000000..c864f5b
--- /dev/null
+++ b/docs/quickstart.rst
@@ -0,0 +1,180 @@
+===========
+Quick start
+===========
+
+First, install Apache log4php.
+
+You may also like to read the `introduction <introduction.html>`_ chapter to 
+familiarise yoursef with the basic concepts used throughout the documentation 
+and examples.
+
+A trivial example
+-----------------
+
+Just want logging to stdout?
+
+.. code-block:: php
+
+    include('Logger.php');
+    $logger = Logger::getLogger("main");
+    $logger->info("This is an informational message.");
+    $logger->warn("I'm not feeling so good...");
+
+This produces the following output:
+
+.. code-block:: bash
+
+    INFO - This is an informational message.
+    WARN - I'm not feeling so good...
+
+A simple example
+-----------------
+
+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 ``WARN``.
+
+First, create a configuration file named ``config.xml`` containing:
+
+.. code-block:: xml
+    :linenos:
+
+    <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>
+
+This configuration file does the following:
+
+- *line 2*: Creates an appender named ``myAppender`` using appender class ``LoggerAppenderFile``
+  which is used for logging to a file.
+- *line 3*: Sets the ``file`` parameter, which tells the appender to which file to write.
+- *line 6*: Sets the root logger level to ``WARN``. This means that logging requests with the level
+  lower than ``WARN`` will not be logged by the root logger.
+- *line 7*: Links ``myAppender`` to 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:
+
+.. code-block:: php
+
+    // 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
+
+This will create a file named ``myLog.log`` containing the following output:
+
+.. code-block:: bash
+
+    WARN - My fourth message.
+    ERROR - My fifth message.
+    FATAL - My sixth message.
+
+An advanced example
+-------------------
+
+This example covers named loggers, layouts and best practices in object-oriented programming.
+
+Create a configuration file named ``config.xml`` with the following content:
+
+.. code-block:: xml
+
+    <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>
+
+The configuration defines two appenders: one writes to the console, and the other to a file.
+
+The
+console appender doesn't have a layout defined, so it will revert to default layout
+(``LoggerLayoutSimple``). The file appender uses a different layout
+(``LoggerLayoutPattern``) 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`` also inherits appenders from the root logger (in this case the console
+appender). This means that logging events sent to the ``Foo`` logger will be logged both to the
+console and the file.
+
+Consider the following code snippet:
+
+.. code-block:: php
+
+    // 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();
+
+This produces the following output in the console:
+
+.. code-block:: bash
+
+    INFO - We have liftoff.
+
+And the following in the log file:
+
+.. code-block:: bash
+
+    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.

http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/requirements.txt
----------------------------------------------------------------------
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000..3ef90b4
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1 @@
+Sphinx==1.1.3


Mime
View raw message