You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by ih...@apache.org on 2013/12/14 15:56:48 UTC
[02/23] Initial implementation of the new manual
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/_theme/log4php/static/log4php.css_t
----------------------------------------------------------------------
diff --git a/docs/_theme/log4php/static/log4php.css_t b/docs/_theme/log4php/static/log4php.css_t
new file mode 100644
index 0000000..5c2439e
--- /dev/null
+++ b/docs/_theme/log4php/static/log4php.css_t
@@ -0,0 +1,63 @@
+/* -- layout ---------------------------------------------------------------- */
+
+.layout-table { width: 100%; }
+.sidebar { width: 250px; vertical-align: top; }
+.content { padding-left: 20px; vertical-align: top; }
+.footer { background-color: whitesmoke; padding: 15px; margin-top: 15px; text-align: right; border-top: 1px solid #EEEEEE; }
+.footer p { font-size: 11px; margin: 0 }
+
+.breadcrumbs { margin-left: 0 }
+.breadcrumbs li { display: inline }
+
+.section h2 { margin-bottom: 10px; }
+.section h3 { margin-bottom: 10px; }
+.section h4 { margin-bottom: 10px; }
+
+h1 { font-size: 31.5px }
+h2 { font-size: 24.5px }
+h3 { font-size: 17.5px }
+h4 { font-size: 14px }
+h5 { font-size: 11.9px }
+
+/* -- header links ---------------------------------------------------------- */
+
+a.headerlink { visibility: hidden; margin-left: 10px; color: lightgrey; }
+a.headerlink:hover { text-decoration: none; }
+
+h1:hover > a.headerlink,
+h2:hover > a.headerlink,
+h3:hover > a.headerlink,
+h4:hover > a.headerlink,
+h5:hover > a.headerlink,
+h6:hover > a.headerlink,
+dt:hover > a.headerlink { visibility: visible; }
+
+/* -- admonitions ----------------------------------------------------------- */
+
+/* grey bordered elements */
+.admonition,
+.deprecated,
+.versionadded { padding: 5px 10px; border: 1px solid #CCC; border-radius: 4px; }
+
+.admonition-title { font-size: 1.2em; font-weight: bold; }
+.admonition.note { color: #3A87AD; background-color: #D9EDF7; border-color: #BCE8F1; }
+.admonition.warning { color: #B94A48; background-color: #F2DEDE; border-color: #EED3D7; }
+
+.deprecated { color: #B94A48; background-color: #F2DEDE; border-color: #EED3D7;}
+.deprecated .versionmodified { font-style: italic; }
+
+.versionadded { color: #3A87AD; background-color: #D9EDF7; border-color: #BCE8F1; }
+.versionadded .versionmodified { font-style: italic; }
+
+/* -- tabs ------------------------------------------------------------------ */
+
+.container.tabs { margin: inherit; width: inherit }
+.container.tabs ul { list-style: none; padding: 0; margin: 10px 0 0 0; }
+.container.tabs li { display:inline; margin-left: 8px; padding: 5px 15px 3px 15px; border: 1px solid #CCC; border-bottom: none; margin-bottom: -1px; }
+.container.tabs li.active { border-bottom: none; background-color: lemonchiffon }
+.container.tabs li a { text-decoration: none }
+
+
+.highlighttable { width: 100%; }
+.highlighttable td.linenos { width: 22px; text-align: right; padding-right: 5px }
+.highlighttable td.linenos pre { padding: 5px 0px; border: 0; background-color: transparent; color: #aaa }
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/_theme/log4php/static/log4php.js
----------------------------------------------------------------------
diff --git a/docs/_theme/log4php/static/log4php.js b/docs/_theme/log4php/static/log4php.js
new file mode 100644
index 0000000..4f9b92c
--- /dev/null
+++ b/docs/_theme/log4php/static/log4php.js
@@ -0,0 +1,55 @@
+$(function() {
+ reformatTabs();
+ activateTabs();
+});
+
+function reformatTabs()
+{
+ $('.container.tabs').each(function(tabs_id, container) {
+ var i, count, title, tabID;
+ var $menu, $tabs, $tab, $titles;
+
+ $tabs = $(container).children('div');
+ $titles = $(container).children('p.rubric');
+
+ if ($tabs.size() < 1) {
+ console.warn("Tab init failed. Not enough <div>s. Required at least 1.");
+ }
+
+ if ($tabs.size() !== $titles.size()) {
+ console.warn("Tab init failed. Number of <div>s does not match number of <p.rubric>s.");
+ return;
+ }
+
+ count = $tabs.size();
+ $menu = $('<ul>');
+
+ for (i = 0; i < count; i++) {
+ $tab = $($tabs[i]);
+ title = $titles[i].innerHTML;
+ tabID = 'tab-' + tabs_id + '-' + i;
+
+ $($titles[i]).remove();
+ $menu.append('<li><a href="#' + tabID + '">' + title + '</a></li>');
+ $tab.attr('id', tabID);
+ }
+
+ $(container).prepend($menu);
+ })
+}
+
+function activateTabs()
+{
+ $('.container.tabs > div').hide();
+ $('.container.tabs > div:first').show();
+ $('.container.tabs ul li:first').addClass('active');
+
+ $('.container.tabs ul li a').click(function(){
+ $('.container.tabs ul li').removeClass('active');
+ $(this).parent().addClass('active');
+ var currentTab = $(this).attr('href');
+ $('.container.tabs > div').hide();
+ $(currentTab).show();
+ return false;
+ });
+}
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/_theme/log4php/theme.conf
----------------------------------------------------------------------
diff --git a/docs/_theme/log4php/theme.conf b/docs/_theme/log4php/theme.conf
new file mode 100644
index 0000000..182df58
--- /dev/null
+++ b/docs/_theme/log4php/theme.conf
@@ -0,0 +1,4 @@
+[theme]
+inherit = none
+stylesheet = log4php.css
+pygments_style = default
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/appenders/console.rst
----------------------------------------------------------------------
diff --git a/docs/appenders/console.rst b/docs/appenders/console.rst
new file mode 100644
index 0000000..ec88d1f
--- /dev/null
+++ b/docs/appenders/console.rst
@@ -0,0 +1,72 @@
+=====================
+LoggerAppenderConsole
+=====================
+
+``LoggerAppenderConsole`` writes logging events to the ``php://stdout`` or the
+``php://stderr`` stream, the former being the default target.
+
+Layout
+------
+
+This appender requires a layout. If no layout is specified in configuration,
+``LoggerLayoutSimple`` will be used by default.
+
+Parameters
+----------
+
++-----------+--------+----------+---------+-------------------------------------------------------+
+| Parameter | Type | Required | Default | Description |
++===========+========+==========+=========+=======================================================+
+| target | string | No | stdout | The stream to write to; either "stdout" or "stderr". |
++-----------+--------+----------+---------+-------------------------------------------------------+
+
+Examples
+--------
+
+This example shows how to configure ``LoggerAppenderConsole``.
+
+.. container:: tabs
+
+ .. rubric:: XML format
+ .. code-block:: xml
+
+ <configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderConsole">
+ <layout class="LoggerLayoutSimple" />
+ </appender>
+ <root>
+ <appender_ref ref="default" />
+ </root>
+ </configuration>
+
+ .. rubric:: PHP format
+ .. code-block:: php
+
+ array(
+ 'appenders' => array(
+ 'default' => array(
+ 'class' => 'LoggerAppenderConsole',
+ 'layout' => array(
+ 'class' => 'LoggerLayoutSimple',
+ ),
+ ),
+ ),
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ ),
+ );
+
+.. 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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/appenders/daily-file.rst
----------------------------------------------------------------------
diff --git a/docs/appenders/daily-file.rst b/docs/appenders/daily-file.rst
new file mode 100644
index 0000000..0e5ec57
--- /dev/null
+++ b/docs/appenders/daily-file.rst
@@ -0,0 +1,126 @@
+=======================
+LoggerAppenderDailyFile
+=======================
+
+``LoggerAppenderDailyFile`` writes logging events to a file which is rolled over
+depending on the date/time of the logging event. By default, the file is rolled
+over daily, hence the appender name. However, the appender can just as easily be
+configured to roll over once a month, or even every minute if desired.
+
+Unlike ``LoggerAppenderFile``, the target file is not static, and can change
+during script execution as the time passes. Destination file is determined by
+two parameters: ``file`` and ``datePattern``.
+
+The path specified in the ``file`` parameter should contain the string ``%s``.
+Each time an event is logged, this string will be substituted with the event's
+date/time formatted according to ``datePattern`` and the event will be logged to
+the resulting file path.
+
+The date/time is formatted according to format string specified in the
+``datePattern`` parameter. The format uses the same rules as the PHP `date()
+<http://php.net/manual/en/function.date.php>`_ function. Any format string
+supported by ``date()`` function may be used as a date pattern.
+
+Layout
+------
+
+This appender requires a layout. If no layout is specified in configuration,
+``LoggerLayoutSimple`` will be used by default.
+
+Parameters
+----------
+
+The following parameters are available:
+
++-------------+---------+----------+---------+-------------------------------------------------------+
+| Parameter | Type | Required | Default | Description |
++=============+=========+==========+=========+=======================================================+
+| file | string | **Yes** | - | Path to the target file. Should contain a ``%s`` |
+| | | | | which gets substituted by the date. |
++-------------+---------+----------+---------+-------------------------------------------------------+
+| append | boolean | No | true | If set to true, the appender will append to the file, |
+| | | | | otherwise the file contents will be overwritten. |
++-------------+---------+----------+---------+-------------------------------------------------------+
+| datePattern | string | No | Ymd | Format for the date in the file path, follows |
+| | | | | formatting rules used by the PHP date() function. |
++-------------+---------+----------+---------+-------------------------------------------------------+
+
+Examples
+--------
+
+Consider the following configuration:
+
+.. container:: tabs
+
+ .. rubric:: XML format
+ .. code-block:: xml
+
+ <configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderDailyFile">
+ <layout class="LoggerLayoutSimple" />
+ <param name="file" value="file-%s.log" />
+ <param name="datePattern" value="Y-m-d" />
+ </appender>
+ <root>
+ <appender_ref ref="default" />
+ </root>
+ </configuration>
+
+ .. rubric:: PHP format
+ .. code-block:: php
+
+ array(
+ 'appenders' => array(
+ 'default' => array(
+ 'class' => 'LoggerAppenderDailyFile',
+ 'layout' => array(
+ 'class' => 'LoggerLayoutSimple',
+ ),
+ 'params' => array(
+ 'datePattern' => 'Y-m-d',
+ 'file' => 'file-%s.log',
+ ),
+ ),
+ ),
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ ),
+ );
+
+In this example, the date pattern is set to ``Y-m-d`` (year, month, day) and
+the target file to ``daily.%s.log``.
+
+Each time this appender receives a logging event, it will:
+
+* Format the event date/time according to the configured date pattern. Let's say
+ this sample is run during 10th of July 2012, then the formatted date is
+ ``2012-07-10``
+* Replace the ``%s`` in the filename with the formated date to get the target
+ file. In this case, the target file will be ``daily.2012-07-10.log``.
+* Write to the target file.
+
+If you continue logging using the given configuration, the appender will
+continue to log to ``daily.2012-07-10.log``, until the date changes. At that
+point it will start logging to ``daily.2012-07-11.log``.
+
+Similarly, date pattern ``Y-m`` will result in filenames like
+``file-2012-07.log``, which will result in monthly rollover.
+
+Hours, minutes and seconds can also be used. Pattern ``Y-m-d.H.i.s`` will result
+in filenames similar to ``file-2012-07-03.10.37.15.log``. In this case, a new
+file will be created each second.
+
+.. 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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/appenders/echo.rst
----------------------------------------------------------------------
diff --git a/docs/appenders/echo.rst b/docs/appenders/echo.rst
new file mode 100644
index 0000000..9f06db8
--- /dev/null
+++ b/docs/appenders/echo.rst
@@ -0,0 +1,84 @@
+==================
+LoggerAppenderEcho
+==================
+
+``LoggerAppenderEcho`` writes logging events using PHP's
+`echo() <http://php.net/manual/en/function.echo.php>`_ function.
+
+Echo outputs may be buffered.
+
+Layout
+------
+
+This appender requires a layout. If no layout is specified in configuration,
+``LoggerLayoutSimple`` will be used by default.
+
+Parameters
+----------
+
+The following parameters are available:
+
++----------------+---------+----------+---------+--------------------------------------------------+
+| Parameter | Type | Required | Default | Description |
++================+=========+==========+=========+==================================================+
+| htmlLineBreaks | boolean | No | false | If set to true, a ``<br />`` element will be |
+| | | | | inserted before each line break in the logged |
+| | | | | message. |
++----------------+---------+----------+---------+--------------------------------------------------+
+
+Examples
+--------
+
+
+This example shows how to configure ``LoggerAppenderEcho`` using the
+``TTCC layout`` with ``htmlLineBreaks`` turned on.
+
+.. container:: tabs
+
+ .. rubric:: XML format
+ .. code-block:: xml
+
+ <configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderEcho">
+ <layout class="LoggerLayoutSimple" />
+ <param name="htmlLineBreaks" value="true" />
+ </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',
+ ),
+ 'params' => array(
+ 'htmlLineBreaks' => 'true',
+ ),
+ ),
+ ),
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ ),
+ );
+
+.. 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.
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/appenders/file.rst
----------------------------------------------------------------------
diff --git a/docs/appenders/file.rst b/docs/appenders/file.rst
new file mode 100644
index 0000000..521e8c4
--- /dev/null
+++ b/docs/appenders/file.rst
@@ -0,0 +1,91 @@
+==================
+LoggerAppenderFile
+==================
+
+``LoggerAppenderFile`` writes logging events to a file.
+
+Layout
+------
+
+This appender requires a layout. If no layout is specified in configuration,
+``LoggerLayoutSimple`` will be used by default.
+
+Parameters
+----------
+
+The following parameters are available:
+
++-------------+---------+----------+---------+-------------------------------------------------------+
+| Parameter | Type | Required | Default | Description |
++=============+=========+==========+=========+=======================================================+
+| file | string | **Yes** | - | Path to the target file. Relative paths are resolved |
+| | | | | based on the working directory. |
++-------------+---------+----------+---------+-------------------------------------------------------+
+| append | boolean | No | true | If set to true, the appender will append to the file, |
+| | | | | otherwise the file contents will be overwritten. |
++-------------+---------+----------+---------+-------------------------------------------------------+
+
+
+Examples
+--------
+
+This example shows how to configure ``LoggerAppenderFile`` to write to
+``file.log`` and to overwrite any content present in the file. The target file
+will be created in the current working directory.
+
+It is also possible to specify an absolute path to the target file, such as
+``/var/log/file.log`` or ``D:/logs/file.log``
+
+
+.. container:: tabs
+
+ .. rubric:: XML format
+ .. code-block:: xml
+
+ <configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderFile">
+ <layout class="LoggerLayoutSimple" />
+ <param name="file" value="file.log" />
+ <param name="append" value="false" />
+ </appender>
+ <root>
+ <appender_ref ref="default" />
+ </root>
+ </configuration>
+
+ .. rubric:: PHP format
+ .. code-block:: php
+
+ array(
+ 'appenders' => array(
+ 'default' => array(
+ 'class' => 'LoggerAppenderFile',
+ 'layout' => array(
+ 'class' => 'LoggerLayoutSimple',
+ ),
+ 'params' => array(
+ 'file' => 'file.log',
+ 'append' => false
+ ),
+ ),
+ ),
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ ),
+ );
+
+.. 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.
+
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/appenders/firephp.rst
----------------------------------------------------------------------
diff --git a/docs/appenders/firephp.rst b/docs/appenders/firephp.rst
new file mode 100644
index 0000000..8296c2d
--- /dev/null
+++ b/docs/appenders/firephp.rst
@@ -0,0 +1,87 @@
+=====================
+LoggerAppenderFirePHP
+=====================
+
+``LoggerAppenderFirePHP`` logs events via the
+`FirePHP <http://www.firephp.org/>`_ serverside library. The messages are logged
+in HTTP headers and can be viewed using the
+`Developer compainion <http://developercompanion.com/>`_ plugin for Firefox.
+
+Requires the FirePHP server-side library 1.0 or greater. Download it from
+`here <http://sourcemint.com/github.com/firephp/firephp/1>`_
+
+.. warning::
+
+ This appender is still experimental. Behaviour may change in future versions
+ without notification.
+
+Layout
+------
+
+This appender requires a layout. If no layout is specified in configuration,
+``LoggerLayoutSimple`` will be used by default.
+
+Parameters
+----------
+
+The following parameters are available:
+
++-------------+---------+----------+---------+-------------------------------------------------------+
+| Parameter | Type | Required | Default | Description |
++=============+=========+==========+=========+=======================================================+
+| target | string | No | page | The target to which messages will be sent. Possible |
+| | | | | options are 'page' (default), 'request', 'package' |
+| | | | | and 'controller'. For more details, see FirePHP |
+| | | | | documentation. |
++-------------+---------+----------+---------+-------------------------------------------------------+
+
+Examples
+--------
+
+Sample configuration:
+
+.. container:: tabs
+
+ .. rubric:: XML format
+ .. code-block:: xml
+
+ <configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderFirePHP">
+ <layout class="LoggerLayoutSimple" />
+ </appender>
+ <root>
+ <appender_ref ref="default" />
+ </root>
+ </configuration>
+
+ .. rubric:: PHP format
+ .. code-block:: php
+
+ array(
+ 'appenders' => array(
+ 'default' => array(
+ 'class' => 'LoggerAppenderFirePHP',
+ 'layout' => array(
+ 'class' => 'LoggerLayoutSimple',
+ ),
+ ),
+ ),
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ ),
+ );
+
+.. 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.
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/appenders/index.rst
----------------------------------------------------------------------
diff --git a/docs/appenders/index.rst b/docs/appenders/index.rst
new file mode 100644
index 0000000..dbb6d1e
--- /dev/null
+++ b/docs/appenders/index.rst
@@ -0,0 +1,126 @@
+=========
+Appenders
+=========
+
+Logging requests can be sent to multiple destinations, such as files, databases,
+syslog and others. Such destinations are called appenders. Appenders are
+attached to `Loggers <./loggers.html>`_ and each logger can have multiple
+attached appenders.
+
+Appender reference
+------------------
+
+The following appender classes are available:
+
+.. toctree::
+ :maxdepth: 1
+
+ console
+ daily-file
+ echo
+ file
+ firephp
+ mail
+ mail-event
+ mongodb
+
+Configuring appenders
+---------------------
+
+.. code-block:: xml
+
+ <configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderFile">
+ <layout class="LoggerLayoutSimple" />
+ <param name="file" value="/var/log/my.log" />
+ <param name="append" value="true" />
+ </appender>
+ <root>
+ <appender_ref ref="default" />
+ </root>
+ </configuration>
+
+From the configuration you can see that an appender has the following
+properties:
+
+* A **name** which uniquely identifies it, in this case *default*.
+
+* A **class** which specifies which appender class will be used to handle the
+ requests. Since we wish to log to a file, ``LoggerAppenderFile`` is used in
+ this case.
+
+* A **layout** which transforms the logging events to string which can be
+ logged. A layout is required by most appenders, but some do not require it,
+ such as the database appender. If a layout is not defined, the appenders will
+ use a default layout.
+
+* Zero or more **parameters** which configure the appender behaviour. In this
+ example, the *file* parameter governs the path to the file which will be used
+ for logging, and *append* defines that log messages should be appended to the
+ file, instead of truncating it.
+
+Linking appenders to loggers
+----------------------------
+
+A logger can be linked to one or more appenders. Also, multiple loggers can
+share the same appender.
+
+Consider the following configuration:
+
+.. code-block:: xml
+
+ <log4php:configuration xmlns:log4php="http://logging.apache.org/log4php/">
+ <appender name="primus" class="LoggerAppenderConsole" />
+ <appender name="secundus" class="LoggerAppenderFile">
+ <param name="file" value="/var/log/my.log" />
+ </appender>
+ <logger name="main">
+ <appender_ref ref="primus" />
+ <appender_ref ref="secundus" />
+ </logger>
+ <logger name="alternative">
+ <appender_ref ref="primus" />
+ </logger>
+ </log4php:configuration>
+
+This configures two appenders, called *primus* and *secundus*, and two loggers
+named *main* and *alternative*. The logger *main* is linked to *primus* and
+*secundus* and will therefore forward logging events to both of them. In other
+words, it will log both to console and to a file. Logger *alternative* is only
+linked to appender *primus* and will therefore only log to the console.
+
+Appender threshold
+------------------
+
+An appender can be assigned a threshold level. All logging requests with level
+lower than this threshold will be ignored.
+
+For example, if you set ``WARN`` as a threshold, then ``INFO``, ``DEBUG`` and
+``TRACE`` level events recieved by the appender will not be logged, but
+``WARN``, ``ERROR`` and ``FATAL`` will.
+
+An example of setting an appender threshold:
+
+.. code-block:: xml
+
+ <configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderEcho" threshold="WARN" />
+ <root>
+ <appender_ref ref="default" />
+ </root>
+ </configuration>
+
+.. 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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/appenders/mail-event.rst
----------------------------------------------------------------------
diff --git a/docs/appenders/mail-event.rst b/docs/appenders/mail-event.rst
new file mode 100644
index 0000000..c6378dd
--- /dev/null
+++ b/docs/appenders/mail-event.rst
@@ -0,0 +1,90 @@
+=======================
+LoggerAppenderMailEvent
+=======================
+
+``LoggerAppenderMailEvent`` appends individual log events via email.
+
+This appender is similar to ``LoggerAppenderMail``, except that it sends each
+each log event in an individual email message at the time when it occurs.
+
+Layout
+------
+
+This appender requires a layout. If no layout is specified in configuration,
+``LoggerLayoutSimple`` will be used by default.
+
+Parameters
+----------
+
+The following parameters are available:
+
++-----------+---------+----------+-----------+---------------------------------------------------------+
+| Parameter | Type | Required | Default | Description |
++===========+=========+==========+===========+=========================================================+
+| to | string | **Yes** | | Email address(es) to which the log will be sent. |
+| | | | | Multiple email addresses may be specified by separating |
+| | | | | them with a comma. |
++-----------+---------+----------+-----------+---------------------------------------------------------+
+| from | string | **Yes** | | Email address which will be used in the From field. |
++-----------+---------+----------+-----------+---------------------------------------------------------+
+| subject | string | No | Log4php | Subject of the email message. |
+| | | | Report | |
++-----------+---------+----------+-----------+---------------------------------------------------------+
+| smtpHost | string | No | SMTP from | Used to override the SMTP server. |
+| | | | php.ini | **Only works on Windows** |
++-----------+---------+----------+-----------+---------------------------------------------------------+
+| port | string | No | 25 | Used to override the default SMTP server port. |
+| | | | | **Only works on Windows** |
++-----------+---------+----------+-----------+---------------------------------------------------------+
+
+.. container:: tabs
+
+ .. rubric:: XML format
+ .. code-block:: xml
+
+ <configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderMailEvent">
+ <layout class="LoggerLayoutSimple" />
+ <param name="to" value="foo@example.com,baz@example.com" />
+ <param name="from" value="logger@example.com" />
+ </appender>
+ <root>
+ <appender_ref ref="default" />
+ </root>
+ </configuration>
+
+ .. rubric:: PHP format
+ .. code-block:: php
+
+ array(
+ 'appenders' => array(
+ 'default' => array(
+ 'class' => 'LoggerAppenderMailEvent',
+ 'layout' => array(
+ 'class' => 'LoggerLayoutSimple',
+ ),
+ 'params' => array(
+ 'to' => 'foo@example.com,baz@example.com',
+ 'from' => 'logger@example.com'
+ ),
+ ),
+ ),
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ ),
+ );
+
+.. 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.
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/appenders/mail.rst
----------------------------------------------------------------------
diff --git a/docs/appenders/mail.rst b/docs/appenders/mail.rst
new file mode 100644
index 0000000..b5aa6c9
--- /dev/null
+++ b/docs/appenders/mail.rst
@@ -0,0 +1,99 @@
+==================
+LoggerAppenderMail
+==================
+
+``LoggerAppenderMail`` appends log events via email.
+
+This appender does not send individual emails for each logging requests but will
+collect them in a buffer and send them all in a single email once the appender
+is closed (i.e. when the script exists). Because of this, it may not appropriate
+for long running scripts, in which case `LoggerAppenderMailEvent`_ might be a
+better choice.
+
+.. _LoggerAppenderMailEvent: mail-event.html
+
+.. warning::
+
+ When working in Windows, make sure that the ``SMTP`` and ``smpt_port``
+ values in php.ini are set to the correct values for your email server
+ (address and port).
+
+
+Layout
+------
+
+This appender requires a layout. If no layout is specified in configuration,
+``LoggerLayoutSimple`` will be used by default.
+
+Parameters
+----------
+
+The following parameters are available:
+
++-----------+---------+----------+---------+---------------------------------------------------------+
+| Parameter | Type | Required | Default | Description |
++===========+=========+==========+=========+=========================================================+
+| to | string | **Yes** | | Email address(es) to which the log will be sent. |
+| | | | | Multiple email addresses may be specified by separating |
+| | | | | them with a comma. |
++-----------+---------+----------+---------+---------------------------------------------------------+
+| from | string | **Yes** | | Email address which will be used in the From field. |
++-----------+---------+----------+---------+---------------------------------------------------------+
+| subject | string | No | Log4php | Subject of the email message. |
+| | | | Report | |
++-----------+---------+----------+---------+---------------------------------------------------------+
+
+Examples
+--------
+
+.. container:: tabs
+
+ .. rubric:: XML format
+ .. code-block:: xml
+
+ <configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderMail">
+ <layout class="LoggerLayoutSimple" />
+ <param name="to" value="foo@example.com,baz@example.com" />
+ <param name="from" value="logger@example.com" />
+ </appender>
+ <root>
+ <appender_ref ref="default" />
+ </root>
+ </configuration>
+
+ .. rubric:: PHP format
+ .. code-block:: php
+
+ array(
+ 'appenders' => array(
+ 'default' => array(
+ 'class' => 'LoggerAppenderMail',
+ 'layout' => array(
+ 'class' => 'LoggerLayoutSimple',
+ ),
+ 'params' => array(
+ 'to' => 'foo@example.com,baz@example.com',
+ 'from' => 'logger@example.com'
+ ),
+ ),
+ ),
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ ),
+ );
+
+.. 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.
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/appenders/mongodb.rst
----------------------------------------------------------------------
diff --git a/docs/appenders/mongodb.rst b/docs/appenders/mongodb.rst
new file mode 100644
index 0000000..e6ea3d6
--- /dev/null
+++ b/docs/appenders/mongodb.rst
@@ -0,0 +1,92 @@
+=====================
+LoggerAppenderMongoDB
+=====================
+
+``LoggerAppenderMongoDB`` appends log events to a MongoDB instance.
+
+MongoDB_ is a scalable, high-performance, open source, document-oriented database.
+
+.. _MongoDB: http://www.mongodb.org/
+
+Layout
+------
+This appender does not require a layout.
+
+Parameters
+----------
+The following parameters are available:
+
++--------------+---------+----------+---------------------+-----------------------------------------------+
+| Parameter | Type | Required | Default | Description |
++==============+=========+==========+=====================+===============================================+
+| host | string | No | mongodb://localhost | Server on which mongodb instance is located. |
++--------------+---------+----------+---------------------+-----------------------------------------------+
+| port | integer | No | 27017 | Port on which the instance is bound. |
++--------------+---------+----------+---------------------+-----------------------------------------------+
+| databaseName | string | No | log4php_mongodb | Name of the database to which to log. |
++--------------+---------+----------+---------------------+-----------------------------------------------+
+| username | string | No | | Username used to connect to the database. |
++--------------+---------+----------+---------------------+-----------------------------------------------+
+| password | string | No | | Password used to connect to the database. |
++--------------+---------+----------+---------------------+-----------------------------------------------+
+| timeout | integer | No | 3000 | For how long the driver should try to connect |
+| | | | | to the database (in milliseconds). |
++--------------+---------+----------+---------------------+-----------------------------------------------+
+
+.. versionadded:: 2.2.0
+ The ``timeout`` parameter.
+
+Examples
+--------
+This example shows how to configure ``LoggerAppenderMongoDB`` to log to a remote
+database.
+
+.. container:: tabs
+
+ .. rubric:: XML format
+ .. code-block:: xml
+
+ <configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderMongoDB">
+ <param name="host" value="mongodb://example.com" />
+ <param name="username" value="logger" />
+ <param name="password" value="secret" />
+ </appender>
+ <root>
+ <appender_ref ref="default" />
+ </root>
+ </configuration>
+
+ .. rubric:: PHP format
+ .. code-block:: php
+
+ array(
+ 'appenders' => array(
+ 'default' => array(
+ 'class' => 'LoggerAppenderMongoDB',
+ 'params' => array(
+ 'host' => 'mongodb://example.com',
+ 'username' => 'logger',
+ 'password' => 'secret',
+ ),
+ ),
+ ),
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ ),
+ );
+
+.. 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.
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/conf.py
----------------------------------------------------------------------
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..fc6fbd7
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,303 @@
+# -*- coding: utf-8 -*-
+#
+# Apache log4php documentation build configuration file, created by
+# sphinx-quickstart on Sun Nov 25 11:38:30 2012.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+from os.path import abspath, dirname, join
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.append(abspath(join(dirname(__file__), "_ext")))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ["log4phpdocs"]
+
+# Add any paths that contain templates here, relative to this directory.
+# templates_path = []
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Apache log4php'
+copyright = u'2012, Apache Software Foundation'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '2.3.1'
+# The full version, including alpha/beta/rc tags.
+release = '2.3.1-dev'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build', '_env', 'README.rst']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'default'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'log4php'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+html_theme_path = ["_theme"]
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+html_favicon = "favicon.ico"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+#html_static_path = ["_static"]
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# HTML translator class for the builder
+html_translator_class = "log4phpdocs.Log4phpHTMLTranslator"
+
+# Content template for the index page.
+#html_index = ''
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Apachelog4phpdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+ ('index', 'Apachelog4php.tex', u'Apache log4php Documentation',
+ 'Apache Software Foundation', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('index', 'apachelog4php', u'Apache log4php Documentation', [u'Apache Software Foundation'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+texinfo_documents = [(
+ 'index', 'Apachelog4php', 'Apache log4php Documentation',
+ 'Apache Software Foundation', 'Apachelog4php', 'One line description of project.',
+ 'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+
+# -- Options for Epub output ---------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = 'Apache log4php'
+epub_author = 'Apache Software Foundation'
+epub_publisher = 'Apache Software Foundation'
+epub_copyright = '2012, Apache Software Foundation'
+
+# The language of the text. It defaults to the language option
+# or en if the language is not set.
+#epub_language = ''
+
+# The scheme of the identifier. Typical schemes are ISBN or URL.
+#epub_scheme = ''
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#epub_identifier = ''
+
+# A unique identification for the text.
+#epub_uid = ''
+
+# A tuple containing the cover image and cover page html template filenames.
+#epub_cover = ()
+
+# HTML files that should be inserted before the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_pre_files = []
+
+# HTML files shat should be inserted after the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_post_files = []
+
+# A list of files that should not be packed into the epub file.
+#epub_exclude_files = []
+
+# The depth of the table of contents in toc.ncx.
+#epub_tocdepth = 3
+
+# Allow duplicate toc entries.
+#epub_tocdup = True
+
+
+# -- Additions for log4php -----------------------------------------------------
+
+# Hack to enable PHP highlighting for PHP code not between "<?php" "?>" by default
+# From: https://github.com/fabpot/sphinx-php
+from sphinx.highlighting import lexers
+from pygments.lexers.web import PhpLexer
+lexers['php'] = PhpLexer(startinline=True)
+
+# Set default highlight language
+highlight_language = 'php'
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/configuration.rst
----------------------------------------------------------------------
diff --git a/docs/configuration.rst b/docs/configuration.rst
new file mode 100644
index 0000000..7da4c15
--- /dev/null
+++ b/docs/configuration.rst
@@ -0,0 +1,278 @@
+=============
+Configuration
+=============
+
+Most components of log4php have various settings which determing their behaviour. They can all be
+configured programatically, but a much more common way is by providing the configuration options
+in a file.
+
+Log4php understands three configuration formats: XML, PHP and Properties, all of which are covered
+in more details in the following sections.
+
+The configuration is passed to log4php by calling the static method ``Logger::configure()``
+before issuing any logging requests. In case log4php is not configured by the time a logging request
+is issued, log4php will configure itself using the `default configuration`_.
+
+XML format
+==========
+
+XML is the most common configuration format, and it is the most prominently featured in the
+documentation and examples.
+
+A simple configuration looks like this:
+
+.. code-block:: xml
+
+ <configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderFile">
+ <layout class="LoggerLayoutSimple" />
+ <param name="file" value="/var/log/my.log" />
+ <param name="append" value="true" />
+ </appender>
+ <root>
+ <appender_ref ref="default" />
+ </root>
+ </configuration>
+
+Detailed instructions on configuring each component is outlined in the corresponding compomnent's
+documentation:
+
+.. toctree::
+ :maxdepth: 1
+
+ appenders/index
+ layouts/index
+
+PHP format
+==========
+
+Configuration can also be stored in a PHP array. This is the format used internally by log4php. All
+other formats are converted to a PHP array before being used by the configurator. Because of this,
+the PHP configuration format should be used when performance is important since it will avoid the
+overhead of parsing the ini or XML file.
+
+This format can be used in one of two ways:
+
+The configuration array can directly be passed to ``Logger::configure()``.
+
+.. code-block:: php
+
+ Logger::configure(array(
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ ),
+ 'appenders' => array(
+ 'default' => array(
+ 'class' => 'LoggerAppenderFile',
+ 'layout' => array(
+ 'class' => 'LoggerLayoutSimple'
+ ),
+ 'params' => array(
+ 'file' => '/var/log/my.log',
+ 'append' => true
+ )
+ )
+ )
+ ));
+
+Alternatively a file can be created which holds the PHP configuration array. The file must have the
+``php`` extension and it should *return* the configuration array. For example, a file named
+``config.php`` with the following content:
+
+.. code-block:: php
+
+ return array(
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ ),
+ 'appenders' => array(
+ 'default' => array(
+ 'class' => 'LoggerAppenderFile',
+ 'layout' => array(
+ 'class' => 'LoggerLayoutSimple'
+ ),
+ 'params' => array(
+ 'file' => '/var/log/my.log',
+ 'append' => true
+ )
+ )
+ )
+ );
+
+This file can then be used to configure log4php:
+
+.. code-block:: php
+
+ Logger::configure('config.php');
+
+.. note::
+
+ To translate a XML or properties configuration file to PHP, run the following code:
+
+ .. code-block:: php
+
+ $configurator = new LoggerConfiguratorDefault();
+ $config = $configurator->parse('/path/to/config.xml');
+
+INI format
+==========
+
+The properties configuration format is a legacy method of configuring log4php. It was inherited from
+`Apache log4j <http://logging.apache.org/log4j/1.2/manual.html>`_ and uses the same format. The only
+difference is that lines begin with ``log4php`` instead of ``log4j``.
+
+.. deprecated:: 2.2.0
+ This format has been deprecated. Support will not be removed for the foreseeable future, however
+ it may not be updated to include newly introduced features. It is recommended that you use
+ either the `XML format`_ or `PHP format`_ for configuration.
+
+The properites configuration format does not support filters.
+
+The following is a high level overview of this format:
+
+.. code-block:: ini
+
+ # Appender named "default"
+ log4php.appender.default = LoggerAppenderEcho
+ log4php.appender.default.layout = LoggerLayoutSimple
+
+ # Appender named "file"
+ log4php.appender.file = LoggerAppenderDailyFile
+ log4php.appender.file.layout = LoggerLayoutPattern
+ log4php.appender.file.layout.conversionPattern = %d{ISO8601} [%p] %c: %m (at %F line %L)%n
+ log4php.appender.file.datePattern = Ymd
+ log4php.appender.file.file = target/examples/daily_%s.log
+ log4php.appender.file.threshold = warn
+
+ # Root logger, linked to "default" appender
+ log4php.rootLogger = DEBUG, default
+
+ # Logger named "foo", linked to "default" appender
+ log4php.logger.foo = warn, default
+
+ # Logger named "foo.bar", linked to "file" appender
+ log4php.logger.foo.bar = debug, file
+ log4php.additivity.foo.bar = true
+
+ # Logger named "foo.bar.baz", linked to both "file" and "default" appenders
+ log4php.logger.foo.bar.baz = trace, default, file
+ log4php.additivity.foo.bar.baz = false
+
+ # Renderers for Fruit and Beer classes
+ log4php.renderer.Fruit = FruitRenderer
+ log4php.renderer.Beer = BeerRenderer
+
+ # Setting base threshold
+ log4php.threshold = debug
+
+Default configuration
+=====================
+
+If no configuration is provided before the initial logging request is issued, log4php will configure
+using the default configuration. This consists of a single ``LoggerAppenderEcho`` appender,
+using ``LoggerLayoutSimple``, attached to the root logger and set to the DEBUG level.
+
+The default configuration in PHP format is:
+
+.. code-block:: php
+
+ array(
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ ),
+ 'appenders' => array(
+ 'default' => array(
+ 'class' => 'LoggerAppenderConsole',
+ 'layout' => array(
+ 'class' => 'LoggerLayoutSimple'
+ )
+ )
+ )
+ )
+
+.. note::
+
+ You can fetch the default configuration as a PHP array by running:
+
+ .. code-block:: php
+
+ LoggerConfiguratorDefault::getDefaultConfiguration();
+
+Programmatic configuration
+==========================
+
+It is possible to configure log4php fully programmatically. This requires the user to implement
+their own configurator object. Configurators must implement the ``LoggerConfigurator``
+interface.
+
+Here is an example:
+
+.. code-block:: php
+
+ class MyConfigurator implements LoggerConfigurator {
+
+ public function configure(LoggerHierarchy $hierarchy, $input = null) {
+
+ // Create an appender which logs to file
+ $appFile = new LoggerAppenderFile('foo');
+ $appFile->setFile('D:/Temp/log.txt');
+ $appFile->setAppend(true);
+ $appFile->setThreshold('all');
+ $appFile->activateOptions();
+
+ // Use a different layout for the next appender
+ $layout = new LoggerLayoutPattern();
+ $layout->setConversionPattern("%date %logger %msg%newline");
+ $layout->activateOptions();
+
+ // Create an appender which echoes log events, using a custom layout
+ // and with the threshold set to INFO
+ $appEcho = new LoggerAppenderEcho('bar');
+ $appEcho->setLayout($layout);
+ $appEcho->setThreshold('info');
+ $appEcho->activateOptions();
+
+ // Add both appenders to the root logger
+ $root = $hierarchy->getRootLogger();
+ $root->addAppender($appFile);
+ $root->addAppender($appEcho);
+ }
+ }
+
+To use the configurator, pass it as a second parameter to ``Logger::configure()`` (either
+the name of the class as a string or an instance). Any value passed as ``$configuration``
+will be available in the configure() method of the LoggerConfigurator as ``$input``.
+
+.. code-block:: php
+
+ // User defined configuration (optional)
+ $configuration = array(
+ 'foo' => 1,
+ 'bar' => 2
+ );
+
+ // Passing the configurator as string
+ Logger::configure($configuration, 'MyConfigurator');
+
+ // Passing the configurator as an instance
+ Logger::configure($configuration, new MyConfigurator());
+
+.. note::
+
+ Always call ``activateOptions()`` on all appenders, filters and layouts after setting their
+ configuration parameters. Otherwise, the configuration may not be properly activated.
+
+.. 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.
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/filters/deny-all.rst
----------------------------------------------------------------------
diff --git a/docs/filters/deny-all.rst b/docs/filters/deny-all.rst
new file mode 100644
index 0000000..eb822af
--- /dev/null
+++ b/docs/filters/deny-all.rst
@@ -0,0 +1,91 @@
+===================
+LoggerFilterDenyAll
+===================
+
+``LoggerFilterDenyAll`` simply denies all logging events.
+
+Parameters
+----------
+
+This filter has not configurable parameters.
+
+Example
+-------
+
+This filter is useful for denying any events which were not accepted by any of
+the previous filters.
+
+In the following example we will create a configuration which will log only
+*INFO* level events. This is accomplished by chaining two filters. First is
+``LoggerFilterLevelMatch`` which accepts *INFO* level events and second is
+``LoggerFilterDenyAll`` which denies any events which were not accepted by
+the first filter.
+
+The corresponding configuration is:
+
+.. container:: tabs
+
+ .. rubric:: XML format
+ .. code-block:: xml
+
+ <configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="defualt" class="LoggerAppenderEcho">
+ <filter class="LoggerFilterLevelMatch">
+ <param name="levelToMatch" value="INFO" />
+ <param name="acceptOnMatch" value="true" />
+ </filter>
+ <filter class="LoggerFilterDenyAll" />
+ </appender>
+ <root>
+ <level value="TRACE" />
+ <appender_ref ref="defualt" />
+ </root>
+ </configuration>
+
+ .. rubric:: PHP format
+ .. code-block:: php
+
+ array(
+ 'appenders' => array(
+ 'default' => array(
+ 'class' => 'LoggerAppenderEcho',
+ 'filters' => array(
+ array(
+ 'class' => 'LoggerFilterLevelMatch',
+ 'params' => array(
+ 'levelToMatch' => 'INFO',
+ 'acceptOnMatch' => true
+ )
+ ),
+ array(
+ 'class' => 'LoggerFilterDenyAll',
+ ),
+ )
+ )
+ ),
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ )
+ )
+
+The results can be seen by running the following code sample.
+
+.. code-block:: php
+
+ Logger::configure('config.xml');
+ $log = Logger::getLogger('example');
+
+ $log->trace('tracing');
+ $log->debug('debugging');
+ $log->info('informing');
+ $log->warn('warning');
+ $log->error('erring');
+ $log->fatal('fatality');
+
+The resulting output will be:
+
+.. code-block:: bash
+
+ INFO - informing
+
+As you can see, all events were blocked except for INFO.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/filters/index.rst
----------------------------------------------------------------------
diff --git a/docs/filters/index.rst b/docs/filters/index.rst
new file mode 100644
index 0000000..1c775c4
--- /dev/null
+++ b/docs/filters/index.rst
@@ -0,0 +1,114 @@
+=======
+Filters
+=======
+
+Filtering is a mechanism which allows the user to configure more precisely which
+logging events will be logged by an appender, and which will be ignored.
+
+Multiple filters can be defined on any appender; they will form a filter chain.
+When a logging event is passed onto an appender, the event will first pass
+through the filter chain. Each filter in the chain will examine the logging
+event and make a decision to either:
+
+
+* **ACCEPT** the logging event - The event will be logged without consulting the
+ remaining filters in the chain.
+* **DENY** the logging event - The event will be not logged without consulting
+ the remaining filters in the chain.
+* Remain **NEUTRAL** - No decision is made, therefore the next filter in the
+ chain is consulted. If there are no remaining filters in the chain, the event
+ is logged.
+
+Filter reference
+================
+
+.. toctree::
+ :maxdepth: 1
+
+ deny-all
+ level-match
+ level-range
+ string-match
+
+Configuring filters
+===================
+
+Filters are configurable in the XML and PHP configuration format. They cannot be configured using
+the properties configuration format.
+
+Like appenders and layouts, depending on the class used, filters may have configurable parameters
+which determine their behaviour.
+
+Here is a configuration example:
+
+.. container:: tabs
+
+ .. rubric:: XML format
+ .. code-block:: xml
+
+ <configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="defualt" class="LoggerAppenderEcho">
+ <layout class="LoggerLayoutSimple"/>
+ <filter class="LoggerFilterStringMatch">
+ <param name="stringToMatch" value="interesting" />
+ <param name="acceptOnMatch" value="true" />
+ </filter>
+ <filter class="LoggerFilterLevelRange">
+ <param name="levelMin" value="debug" />
+ <param name="levelMax" value="error" />
+ </filter>
+ </appender>
+ <root>
+ <level value="TRACE" />
+ <appender_ref ref="defualt" />
+ </root>
+ </configuration>
+
+ .. rubric:: PHP format
+ .. code-block:: php
+
+ array(
+ 'appenders' => array(
+ 'default' => array(
+ 'class' => 'LoggerAppenderEcho'
+ 'layout' => array(
+ 'class' => 'LoggerLayoutSimple'
+ ),
+ 'filters' => array(
+ array(
+ 'class' => 'LoggerFilterStringMatch',
+ 'params' => array(
+ 'stringToMatch' => 'interesting',
+ 'acceptOnMatch' => true,
+ )
+ ),
+ array(
+ 'class' => 'LoggerFilterLevelRange',
+ 'params' => array(
+ 'levelMin' => 'debug',
+ 'levelMax' => 'error',
+ )
+ )
+ )
+ )
+ ),
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ )
+ )
+
+In this example, there are two filters defined for the *default* appender.
+
+The first filter ``LoggerFilterStringMatch`` searches for the string
+"interesting" in the logging event's message. If the string is found, the filter
+will ACCEPT the logging event, and the event will be logged. If the string is
+not found, the filter will remain NEUTRAL, and the event will be passed on to
+the next filter.
+
+The second filter ``LoggerFilterLevelRange`` ACCEPTS all events which have a
+level between DEBUG and ERROR (in other words, levels DEBUG, INFO, WARN and
+ERROR). It DENIES all other events.
+
+Therefore, this filter configuration will log events which which have a level
+between DEBUG and ERROR, except of theose which have the string "interesting" in
+the message. Those will be logged regardless of their level.
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/filters/level-match.rst
----------------------------------------------------------------------
diff --git a/docs/filters/level-match.rst b/docs/filters/level-match.rst
new file mode 100644
index 0000000..e351628
--- /dev/null
+++ b/docs/filters/level-match.rst
@@ -0,0 +1,66 @@
+======================
+LoggerFilterLevelMatch
+======================
+
+LoggerFilterLevelMatch either accepts the specified logger level or denies it.
+
+Parameters
+----------
+
+This filter has the following parameters:
+
++---------------+-------------+----------+---------+------------------------------------+
+| Parameter | Type | Required | Default | Description |
++===============+=============+==========+=========+====================================+
+| levelToMatch | LoggerLevel | **Yes** | - | The level to match |
++---------------+-------------+----------+---------+------------------------------------+
+| acceptOnMatch | boolean | No | true | If true, the matching log level is |
+| | | | | accepted, denied otherwise. |
++---------------+-------------+----------+---------+------------------------------------+
+
+Example
+-------
+
+The following filter configuration will deny all logging events with level
+DEBUG. It will remain neutral for others.
+
+.. container:: tabs
+
+ .. rubric:: XML format
+ .. code-block:: xml
+
+ <configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderEcho">
+ <filter class="LoggerFilterLevelMatch">
+ <param name="levelToMatch" value="debug" />
+ <param name="acceptOnMatch" value="false" />
+ </filter>
+ </appender>
+ <root>
+ <level value="trace" />
+ <appender_ref ref="default" />
+ </root>
+ </configuration>
+
+ .. rubric:: PHP format
+ .. code-block:: php
+
+ array(
+ 'appenders' => array(
+ 'default' => array(
+ 'class' => 'LoggerAppenderEcho',
+ 'filters' => array(
+ array(
+ 'class' => 'LoggerFilterLevelMatch',
+ 'params' => array(
+ 'levelToMatch' => 'debug',
+ 'acceptOnMatch' => false
+ )
+ )
+ )
+ )
+ ),
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ )
+ )
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/filters/level-range.rst
----------------------------------------------------------------------
diff --git a/docs/filters/level-range.rst b/docs/filters/level-range.rst
new file mode 100644
index 0000000..14e2685
--- /dev/null
+++ b/docs/filters/level-range.rst
@@ -0,0 +1,70 @@
+======================
+LoggerFilterLevelRange
+======================
+
+This filter accepts or denies logging events if their log level is within the
+specified range.
+
+Parameters
+----------
+
+This filter has the following parameters:
+
++---------------+-------------+----------+---------+----------------------------------------------+
+| Parameter | Type | Required | Default | Description |
++===============+=============+==========+=========+==============================================+
+| levelMin | LoggerLevel | No | | The minimum level to match. If set, events |
+| | | | | with lower levels will not be matched. |
++---------------+-------------+----------+---------+----------------------------------------------+
+| levelMax | LoggerLevel | No | | The maximum level to match. If set, events |
+| | | | | with higher levels will not be matched. |
++---------------+-------------+----------+---------+----------------------------------------------+
+| acceptOnMatch | boolean | No | true | If true, the matching log levels will be |
+| | | | | accepted, otherwise they will be deined. |
++---------------+-------------+----------+---------+----------------------------------------------+
+
+Example
+-------
+
+The following configuration denies event with level lower than warn.
+
+.. container:: tabs
+
+ .. rubric:: XML format
+ .. code-block:: xml
+
+ <configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderEcho">
+ <filter class="LoggerFilterLevelRange">
+ <param name="levelMax" value="warn" />
+ <param name="acceptOnMatch" value="false" />
+ </filter>
+ </appender>
+ <root>
+ <level value="trace" />
+ <appender_ref ref="default" />
+ </root>
+ </configuration>
+
+ .. rubric:: PHP format
+ .. code-block:: php
+
+ array(
+ 'appenders' => array(
+ 'default' => array(
+ 'class' => 'LoggerAppenderEcho',
+ 'filters' => array(
+ array(
+ 'class' => 'LoggerFilterLevelRange',
+ 'params' => array(
+ 'levelMax' => 'warn',
+ 'acceptOnMatch' => false
+ )
+ )
+ )
+ )
+ ),
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ )
+ )
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/filters/string-match.rst
----------------------------------------------------------------------
diff --git a/docs/filters/string-match.rst b/docs/filters/string-match.rst
new file mode 100644
index 0000000..79d3681
--- /dev/null
+++ b/docs/filters/string-match.rst
@@ -0,0 +1,70 @@
+=======================
+LoggerFilterStringMatch
+=======================
+
+This filter allows or denies logging events if their message contains a given
+string.
+
+Parameters
+----------
+
+This filter has the following parameters:
+
++---------------+-----------+----------+---------+--------------------------------------+
+| Parameter | Type | Required | Default | Description |
++===============+===========+==========+=========+======================================+
+| stringToMatch | string | **Yes** | - | The string to match |
++---------------+-----------+----------+---------+--------------------------------------+
+| acceptOnMatch | boolean | No | true | If true, the matching log events are |
+| | | | | accepted, denied otherwise. |
++---------------+-----------+----------+---------+--------------------------------------+
+
+The following filter configuration denies events which contain the string
+"not-interesting" in their message.
+
+Example
+-------
+
+The following filter configuration denies events which contain the string
+"not-interesting" in their message.
+
+.. container:: tabs
+
+ .. rubric:: XML format
+ .. code-block:: xml
+
+ <configuration xmlns="http://logging.apache.org/log4php/">
+ <appender name="default" class="LoggerAppenderEcho">
+ <filter class="LoggerFilterStringMatch">
+ <param name="stringToMatch" value="not-interesting" />
+ <param name="acceptOnMatch" value="false" />
+ </filter>
+ </appender>
+ <root>
+ <level value="trace" />
+ <appender_ref ref="default" />
+ </root>
+ </configuration>
+
+ .. rubric:: PHP format
+ .. code-block:: php
+
+ array(
+ 'appenders' => array(
+ 'default' => array(
+ 'class' => 'LoggerAppenderEcho',
+ 'filters' => array(
+ array(
+ 'class' => 'LoggerFilterStringMatch',
+ 'params' => array(
+ 'stringToMatch' => 'not-interesting',
+ 'acceptOnMatch' => false
+ )
+ )
+ )
+ )
+ ),
+ 'rootLogger' => array(
+ 'appenders' => array('default'),
+ )
+ )
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/index.rst
----------------------------------------------------------------------
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..d13f59d
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,32 @@
+============================
+Apache log4php documentation
+============================
+
+Welcome to Apache log4php.
+
+Contents:
+
+.. toctree::
+ :maxdepth: 1
+
+ introduction
+ quickstart
+ configuration
+ appenders/index
+ layouts/index
+ filters/index
+
+.. 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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/logging-log4php/blob/4780fc1e/docs/introduction.rst
----------------------------------------------------------------------
diff --git a/docs/introduction.rst b/docs/introduction.rst
new file mode 100644
index 0000000..2fbffe6
--- /dev/null
+++ b/docs/introduction.rst
@@ -0,0 +1,65 @@
+============
+Introduction
+============
+
+There are three main concepts in Apache log4php: loggers, appenders and layouts. These three types
+of components work together to enable developers to log messages according to message type and
+level, and to control at runtime how these messages are formatted and where they are reported.
+
+Loggers
+=======
+
+A logger is a component which will take your logging request and log it. Each class in a project
+can have an individual logger, or they can all use a common logger. Loggers are named entities; it
+is common to name them after the class which will use it for logging.
+
+Appenders
+=========
+
+Logging requests can be sent to multiple destinations and such destinations are called appenders.
+Appenders exist for console, files, syslog, database, sockets and other output destinations. One or
+more appenders can be attached to a logger. Each enabled logging request for a given logger will be
+forwarded to all the appenders in that logger.
+
+Layouts
+=======
+
+Layouts are components responsible for transforming a logging event into a string. Most appender
+classes require a layout class to convert the event to a string so that it can be logged.
+
+Levels
+======
+
+A level describes the severity of a logging message. There are six levels, show here in descending
+order of severity.
+
++-------+----------+------------------------------------------------------------------------------------------------+
+| Level | Severity | Description |
++=======+==========+================================================================================================+
+| FATAL | Highest | Very severe error events that will presumably lead the application to abort. |
++-------+----------+------------------------------------------------------------------------------------------------+
+| ERROR | ... | Error events that might still allow the application to continue running. |
++-------+----------+------------------------------------------------------------------------------------------------+
+| WARN | ... | Potentially harmful situations which still allow the application to continue running. |
++-------+----------+------------------------------------------------------------------------------------------------+
+| INFO | ... | Informational messages that highlight the progress of the application at coarse-grained level. |
++-------+----------+------------------------------------------------------------------------------------------------+
+| DEBUG | ... | Fine-grained informational events that are most useful to debug an application. |
++-------+----------+------------------------------------------------------------------------------------------------+
+| TRACE | Lowest | Finest-grained informational events. |
++-------+----------+------------------------------------------------------------------------------------------------+
+
+.. 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.
\ No newline at end of file