<?xml version="1.0" encoding="UTF-8"?>
<!--
 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.
-->
<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">

	<properties>
		<title>Configuration</title>
	</properties>

	<body>
		<section name="Configuration">

			<p>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.</p>

			<p>Log4php understands three configuration formats: XML, PHP and Properties, all of which are covered in 
			more details in the following sections.</p>

			<p>The configuration is passed to log4php by calling the static method <code>Logger::configure()</code>
			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 <a href="#Default_configuration">default configuration</a>.</p>			
			
			<subsection name="XML" id="XML">
			
				<p>XML is the most common configuration format, and it is the most prominently featured in the 
				documentation and examples.</p>
				
				<p>A simple configuration looks like this:</p>
				
<pre class="prettyprint linenums"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<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>
]]></pre>
				
				<p>Detailed instructions on configuring each component is outlined in the corresponding compomnent's 
				documentation: 
				<a href="loggers.html">loggers</a>, 
				<a href="appenders.html">appenders</a>, 
				<a href="layouts.html">layouts</a>,  
				<a href="filters.html">filters</a>, 
				<a href="renderers.html">renderers</a> 
				</p>
			</subsection>
			
			<subsection name="PHP" id="PHP">
			
				<p>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.</p>
				
				<p>This format can be used in one of two ways:</p>
				
				<p>The configuration array can directly be passed to <code>Logger::configure()</code>.</p>

<pre class="prettyprint linenums">
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
            )
        )
    )
));
</pre>
				
				<p>Alternatively a file can be created which holds the PHP configuration array. The file must
				have the <code>php</code> extension and it should <em>return</em> the configuration array. For example, 
				a file named <code>config.php</code> with the following content:</p>
				
<pre class="prettyprint linenums">
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
            )
        )
    )
);
</pre>

				<p>This file can then be used to configure log4php:</p>
				
				<pre class="prettyprint">Logger::configure('config.php');</pre>
				
				<div class="alert alert-info">
					<p><strong>Hint:</strong> to translate a XML or properties configuration file to PHP, run the following code:</p>
<pre class="prettyprint">
$configurator = new LoggerConfiguratorDefault();
$config = $configurator->parse('/path/to/config.xml');
</pre>
				</div>
			</subsection>


			<subsection name="Properties (INI)" id="INI">

				<p>The properties configuration format is a legacy method of configuring log4php. It was inherited from 
				<a href="logging.apache.org/log4j/1.2/manual.html">Apache log4j</a> and uses the same format. The only 
				difference is that lines begin with <code>log4php</code> instead of <code>log4j</code>.</p>
				
				<div class="alert alert-warning">
					<p>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 <a href="#XML">XML</a> or <a href="#PHP">PHP</a> configuration format.</p>
				</div>
				
				<p>The properites configuration format does not support filters.</p>
				
				<p>The following is a high level overview of this format:</p>
				
				
<pre class="prettyprint">
# 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
</pre>
			</subsection>

			<subsection name="Default configuration" id="Default_configuration">
				<p>If no configuration is provided before the initial logging request is issued, log4php will configure
				using the default configuration. This consists of a single <code>LoggerAppenderEcho</code> appender,
				using <code>LoggerLayoutSimple</code>, attached to the root logger and set to the DEBUG level.</p>
				
				<p>The default configuration in PHP format is:</p>
				
<pre class="prettyprint linenums">
array(
    'rootLogger' => array(
        'appenders' => array('default'),
    ),
    'appenders' => array(
        'default' => array(
            'class' => 'LoggerAppenderConsole',
            'layout' => array(
                'class' => 'LoggerLayoutSimple'
            )
        )
    )
)
</pre>

				<div class="alert alert-info">
					<p><strong>Hint:</strong> You can fetch the default configuration as a PHP array by running:</p>
					<pre class="prettyprint">LoggerConfiguratorDefault::getDefaultConfiguration();</pre>
				</div>
			</subsection>
			
			<subsection name="Programmatic configuration">
				
				<p>It is possible to configure log4php fully programmatically. This requires the user to implement 
				their own configurator object. Configurators must implement the <code>LoggerConfigurator</code> 
				interface.</p>
				
				<p>Here is an example:</p>

<pre class="prettyprint linenums">
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);
    }
}
</pre>

				<p>To use the configurator, pass it as a second parameter to <code>Logger::configure()</code> (either 
				    the name of the class as a string or an instance). Any value passed as <code>$configuration</code>
				    will be available in the configure() method of the LoggerConfigurator as <code>$input</code>.</p>

<pre class="prettyprint linenums">
// 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());
</pre>
				<div class="alert alert-warning">
					<p><strong>Note: </strong>Always call <code>activateOptions()</code> on all appenders, filters and layouts after setting
					their configuration parameters. Otherwise, the configuration may not be properly activated.</p>
				</div>
			</subsection>
		</section>
	</body>
</document>
