content/log4php/2.3.0/docs/configuration.html - logging-site - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <!-- Generated by Apache Maven Doxia at Oct 13, 2012 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 	<head>
 		<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
 		<title>Apache log4php -
 		Configuration - Apache log4php</title>
 		<link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css" />
 		<link rel="stylesheet" href="../css/site.css" type="text/css" />
 		<script type="text/javascript" src="../js/jquery.min.js"></script>
 		<script type="text/javascript" src="../js/bootstrap.min.js"></script>
 		<script type="text/javascript" src="../js/prettify.min.js"></script>
 		<script type="text/javascript" src="../js/site.js"></script>
 		<meta name="Date-Revision-yyyymmdd" content="20121013" />
 		<meta http-equiv="Content-Language" content="en" />

 					<!-- Google Analytics -->
 		<script type="text/javascript">

 			var _gaq = _gaq || [];
 			_gaq.push(['_setAccount', 'UA-26177991-1']);
 			_gaq.push (['_gat._anonymizeIp']);
 			_gaq.push(['_trackPageview']);

 			(function() {
 				var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
 				ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
 				var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
 			})();

 		</script>
 		</head>
 	<body class="composite">

 		<div class="navbar">
 			<div class="navbar-inner">
 				<div class="container-fluid">
 					<a class="brand" href="http://logging.apache.org/log4php">Apache log4php &trade;</a>
 						<ul class="nav">
 						<li>
 									<a href="../index.html" title="About">About</a>
 			</li>
 					<li>
 									<a href="../download.html" title="Download">Download</a>
 			</li>
 					<li>
 									<a href="../install.html" title="Install">Install</a>
 			</li>
 					<li>
 									<a href="../quickstart.html" title="Quick start">Quick start</a>
 			</li>
 		</ul>

 					<!-- Twitter link -->
 					<ul class="nav pull-right">
 						<li><a href="http://twitter.com/log4php/" class="external">Follow <strong>@log4php</strong></a></li>
 					</ul>

 					<!-- Google CSE Search Box -->
 					<form class="navbar-search pull-right" id="cref" action="http://www.google.com/cse">
 						<input type="hidden" name="cref" value="http://logging.apache.org/log4php/cse.xml" />
 						<input class="search-query pull-left" type="text" name="q" size="40" placeholder="Search" />
 					</form>
 				</div>
 			</div>
 		</div>

 		<div class="container-fluid">
 			<table class="layout-table">
 				<tr>
 					<td class="sidebar">
 						<div class="well sidebar-nav">
 										<ul class="nav nav-list">
 								 <li class="nav-header"><i class="icon-home"></i>Apache log4php™</li>
 																	<li class="none">
 								<a href="../index.html" title="About">About</a>
 			</li>
 										<li class="none">
 								<a href="../download.html" title="Download">Download</a>
 			</li>
 										<li class="none">
 								<a href="../install.html" title="Install">Install</a>
 			</li>
 										<li class="none">
 								<a href="../changelog.html" title="Changelog">Changelog</a>
 			</li>
 							</ul>
 			<ul class="nav nav-list">
 								 <li class="nav-header"><i class="icon-book"></i>Documentation</li>
 																	<li class="none">
 								<a href="../quickstart.html" title="Quick start">Quick start</a>
 			</li>
 										<li class="none">
 								<a href="../docs/introduction.html" title="Introduction">Introduction</a>
 			</li>
 											<li class="none active">
 								<a href="../docs/configuration.html" title="Configuration">Configuration</a>
 			</li>
 										<li class="none">
 								<a href="../docs/loggers.html" title="Loggers">Loggers</a>
 			</li>
 																																																																																																																																																								<li class="collapsed">
 								<a href="../docs/appenders.html" title="Appenders">Appenders</a>
 						</li>
 																																																																																<li class="collapsed">
 								<a href="../docs/layouts.html" title="Layouts">Layouts</a>
 						</li>
 										<li class="none">
 								<a href="../docs/filters.html" title="Filters">Filters</a>
 			</li>
 										<li class="none">
 								<a href="../docs/renderers.html" title="Renderers">Renderers</a>
 			</li>
 										<li class="none">
 								<a href="../apidocs/index.html" title="API documentation">API documentation</a>
 			</li>
 							</ul>
 			<ul class="nav nav-list">
 								 <li class="nav-header"><i class="icon-user"></i>Community</li>
 																	<li class="none">
 								<a href="../volunteering.html" title="Volunteering">Volunteering</a>
 			</li>
 										<li class="none">
 								<a href="../contributingpatches.html" title="Contributing Patches">Contributing Patches</a>
 			</li>
 										<li class="none">


 				<a href="http://wiki.apache.org/logging-log4php" class="external" target="_blank" title="Wiki">Wiki</a>
 			</li>
 										<li class="none">


 				<a href="http://blogs.apache.org/logging/" class="external" target="_blank" title="Blog">Blog</a>
 			</li>
 							</ul>
 			<ul class="nav nav-list">
 								 <li class="nav-header"><i class="icon-info-sign"></i>Project Information</li>
 																	<li class="none">
 								<a href="../integration.html" title="Continuous Integration">Continuous Integration</a>
 			</li>
 										<li class="none">
 								<a href="../source-repository.html" title="Source Repository">Source Repository</a>
 			</li>
 										<li class="none">
 								<a href="../dependencies.html" title="Dependencies">Dependencies</a>
 			</li>
 										<li class="none">
 								<a href="../license.html" title="Project License">Project License</a>
 			</li>
 										<li class="none">
 								<a href="../team-list.html" title="Project Team">Project Team</a>
 			</li>
 										<li class="none">
 								<a href="../issue-tracking.html" title="Issue Tracking">Issue Tracking</a>
 			</li>
 										<li class="none">
 								<a href="../mail-lists.html" title="Mailing Lists">Mailing Lists</a>
 			</li>
 							</ul>
 			<ul class="nav nav-list">
 								 <li class="nav-header"><i class="icon-cog"></i>Project Reports</li>
 																	<li class="none">
 								<a href="../changes-report.html" title="Changes Report">Changes Report</a>
 			</li>
 										<li class="none">
 								<a href="../surefire-report.html" title="Surefire Report">Surefire Report</a>
 			</li>
 										<li class="none">
 								<a href="../rat-report.html" title="RAT Report">RAT Report</a>
 			</li>
 										<li class="none">
 								<a href="../coverage-report/index.html" title="Code Coverage">Code Coverage</a>
 			</li>
 							</ul>
 			<ul class="nav nav-list">
 								 <li class="nav-header"><i class="icon-heart"></i>Apache</li>
 																	<li class="none">


 				<a href="http://www.apache.org" class="external" target="_blank" title="Home">Home</a>
 			</li>
 										<li class="none">


 				<a href="http://www.apache.org/foundation/sponsorship.html" class="external" target="_blank" title="Sponsorship">Sponsorship</a>
 			</li>
 										<li class="none">


 				<a href="http://www.apache.org/licenses/" class="external" target="_blank" title="License">License</a>
 			</li>
 										<li class="none">


 				<a href="http://www.apache.org/foundation/thanks.html" class="external" target="_blank" title="Thanks">Thanks</a>
 			</li>
 										<li class="none">


 				<a href="http://www.apachecon.com" class="external" target="_blank" title="Conferences">Conferences</a>
 			</li>
 										<li class="none">


 				<a href="http://www.apache.org/security/" class="external" target="_blank" title="Security">Security</a>
 			</li>
 							</ul>
 							</div>
 						<div id="poweredBy">
 															<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
 				<img class="poweredBy" alt="Built by Maven" src="../images/logos/maven-feather.png" />
 			</a>
 									</div>
 					</td>
 					<td class="content">
 						<!-- 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. -->


 		<div class="section"><h2>Configuration<a name="Configuration"></a></h2>

 			<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 <tt>Logger::configure()</tt>
 			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>

 			<a name="XML"></a><div class="section" id="XML"><h3>XML<a name="XML"></a></h3>

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

 <div><pre class="prettyprint linenums">
 &lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
 &lt;configuration xmlns=&quot;http://logging.apache.org/log4php/&quot;&gt;
     &lt;appender name=&quot;default&quot; class=&quot;LoggerAppenderFile&quot;&gt;
         &lt;layout class=&quot;LoggerLayoutSimple&quot; /&gt;
         &lt;param name=&quot;file&quot; value=&quot;/var/log/my.log&quot; /&gt;
         &lt;param name=&quot;append&quot; value=&quot;true&quot; /&gt;
     &lt;/appender&gt;
     &lt;root&gt;
         &lt;appender_ref ref=&quot;default&quot; /&gt;
     &lt;/root&gt;
 &lt;/configuration&gt;
 </pre></div>

 				<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>
 			</div>

 			<a name="PHP"></a><div class="section" id="PHP"><h3>PHP<a name="PHP"></a></h3>

 				<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 <tt>Logger::configure()</tt>.</p>

 <div><pre class="prettyprint linenums">
 Logger::configure(array(
     'rootLogger' =&gt; array(
         'appenders' =&gt; array('default'),
     ),
     'appenders' =&gt; array(
         'default' =&gt; array(
             'class' =&gt; 'LoggerAppenderFile',
             'layout' =&gt; array(
                 'class' =&gt; 'LoggerLayoutSimple'
             ),
             'params' =&gt; array(
             	'file' =&gt; '/var/log/my.log',
             	'append' =&gt; true
             )
         )
     )
 ));
 </pre></div>

 				<p>Alternatively a file can be created which holds the PHP configuration array. The file must
 				have the <tt>php</tt> extension and it should <i>return</i> the configuration array. For example,
 				a file named <tt>config.php</tt> with the following content:</p>

 <div><pre class="prettyprint linenums">
 return array(
     'rootLogger' =&gt; array(
         'appenders' =&gt; array('default'),
     ),
     'appenders' =&gt; array(
         'default' =&gt; array(
             'class' =&gt; 'LoggerAppenderFile',
             'layout' =&gt; array(
                 'class' =&gt; 'LoggerLayoutSimple'
             ),
             'params' =&gt; array(
             	'file' =&gt; '/var/log/my.log',
             	'append' =&gt; true
             )
         )
     )
 );
 </pre></div>

 				<p>This file can then be used to configure log4php:</p>

 				<div><pre class="prettyprint">Logger::configure('config.php');</pre></div>

 				<div class="alert alert-info">
 					<p><b>Hint:</b> to translate a XML or properties configuration file to PHP, run the following code:</p>
 <div><pre class="prettyprint">
 $configurator = new LoggerConfiguratorDefault();
 $config = $configurator-&gt;parse('/path/to/config.xml');
 </pre></div>
 				</div>
 			</div>


 			<a name="INI"></a><div class="section" id="INI"><h3>Properties (INI)<a name="Properties_INI"></a></h3>

 				<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 <tt>log4php</tt> instead of <tt>log4j</tt>.</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>


 <div><pre class="prettyprint">
 # Appender named &quot;default&quot;
 log4php.appender.default = LoggerAppenderEcho
 log4php.appender.default.layout = LoggerLayoutSimple

 # Appender named &quot;file&quot;
 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 &quot;default&quot; appender
 log4php.rootLogger = DEBUG, default

 # Logger named &quot;foo&quot;, linked to &quot;default&quot; appender
 log4php.logger.foo = warn, default

 # Logger named &quot;foo.bar&quot;, linked to &quot;file&quot; appender
 log4php.logger.foo.bar = debug, file
 log4php.additivity.foo.bar = true

 # Logger named &quot;foo.bar.baz&quot;, linked to both &quot;file&quot; and &quot;default&quot; 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></div>
 			</div>

 			<a name="Default_configuration"></a><div class="section" id="Default_configuration"><h3>Default configuration<a name="Default_configuration"></a></h3>
 				<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 <tt>LoggerAppenderEcho</tt> appender,
 				using <tt>LoggerLayoutSimple</tt>, attached to the root logger and set to the DEBUG level.</p>

 				<p>The default configuration in PHP format is:</p>

 <div><pre class="prettyprint linenums">
 array(
     'rootLogger' =&gt; array(
         'appenders' =&gt; array('default'),
     ),
     'appenders' =&gt; array(
         'default' =&gt; array(
             'class' =&gt; 'LoggerAppenderConsole',
             'layout' =&gt; array(
                 'class' =&gt; 'LoggerLayoutSimple'
             )
         )
     )
 )
 </pre></div>

 				<div class="alert alert-info">
 					<p><b>Hint:</b> You can fetch the default configuration as a PHP array by running:</p>
 					<div><pre class="prettyprint">LoggerConfiguratorDefault::getDefaultConfiguration();</pre></div>
 				</div>
 			</div>

 			<div class="section"><h3>Programmatic configuration<a name="Programmatic_configuration"></a></h3>

 				<p>It is possible to configure log4php fully programmatically. This requires the user to implement
 				their own configurator object. Configurators must implement the <tt>LoggerConfigurator</tt>
 				interface.</p>

 				<p>Here is an example:</p>

 <div><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-&gt;setFile('D:/Temp/log.txt');
         $appFile-&gt;setAppend(true);
         $appFile-&gt;setThreshold('all');
         $appFile-&gt;activateOptions();

         // Use a different layout for the next appender
         $layout = new LoggerLayoutPattern();
         $layout-&gt;setConversionPattern(&quot;%date %logger %msg%newline&quot;);
         $layout-&gt;activateOptions();

         // Create an appender which echoes log events, using a custom layout
         // and with the threshold set to INFO
         $appEcho = new LoggerAppenderEcho('bar');
         $appEcho-&gt;setLayout($layout);
         $appEcho-&gt;setThreshold('info');
         $appEcho-&gt;activateOptions();

         // Add both appenders to the root logger
         $root = $hierarchy-&gt;getRootLogger();
         $root-&gt;addAppender($appFile);
         $root-&gt;addAppender($appEcho);
     }
 }
 </pre></div>

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

 <div><pre class="prettyprint linenums">
 // User defined configuration (optional)
 $configuration = array(
     'foo' =&gt; 1,
     'bar' =&gt; 2
 );

 // Passing the configurator as string
 Logger::configure($configuration, 'MyConfigurator');

 // Passing the configurator as an instance
 Logger::configure($configuration, new MyConfigurator());
 </pre></div>
 				<div class="alert alert-warning">
 					<p><b>Note: </b>Always call <tt>activateOptions()</tt> on all appenders, filters and layouts after setting
 					their configuration parameters. Otherwise, the configuration may not be properly activated.</p>
 				</div>
 			</div>
 		</div>


 					</td>
 				</tr>
 			</table>
 		</div>

 		<div class="footer">
 			<p>Copyright &#169;										2012
 												<a href="http://www.apache.org">Apache Software Foundation</a>.
 						All Rights Reserved.

 				Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache Software License, Version 2.0</a>.
 			Please read the <a href="../privacy.html">Privacy policy</a></p>
 			<p>Apache log4php, Apache, log4php, the Apache feather logo, the Apache Logging Services project logo and the Built by
 			Maven logo are trademarks of The Apache Software Foundation.</p>
 			<p>Site powered by <a class="external" href="http://twitter.github.com/bootstrap/">Twitter Bootstrap</a>. Icons from
 			<a class="external" href="http://glyphicons.com/">Glyphicons Free</a>.</p>
 		</div>
 	</body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
	<!-- Generated by Apache Maven Doxia at Oct 13, 2012 -->
	<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<title>Apache log4php -
	Configuration - Apache log4php</title>
	<link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css" />
	<link rel="stylesheet" href="../css/site.css" type="text/css" />
	<script type="text/javascript" src="../js/jquery.min.js"></script>
	<script type="text/javascript" src="../js/bootstrap.min.js"></script>
	<script type="text/javascript" src="../js/prettify.min.js"></script>
	<script type="text/javascript" src="../js/site.js"></script>
	<meta name="Date-Revision-yyyymmdd" content="20121013" />
	<meta http-equiv="Content-Language" content="en" />

	<!-- Google Analytics -->
	<script type="text/javascript">

	var _gaq = _gaq \|\| [];
	_gaq.push(['_setAccount', 'UA-26177991-1']);
	_gaq.push (['_gat._anonymizeIp']);
	_gaq.push(['_trackPageview']);

	(function() {
	var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
	ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
	var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
	})();

	</script>
	</head>
	<body class="composite">

	<div class="navbar">
	<div class="navbar-inner">
	<div class="container-fluid">
	<a class="brand" href="http://logging.apache.org/log4php">Apache log4php ™</a>
	<ul class="nav">
	<li>
	<a href="../index.html" title="About">About</a>
	</li>
	<li>
	<a href="../download.html" title="Download">Download</a>
	</li>
	<li>
	<a href="../install.html" title="Install">Install</a>
	</li>
	<li>
	<a href="../quickstart.html" title="Quick start">Quick start</a>
	</li>
	</ul>

	<!-- Twitter link -->
	<ul class="nav pull-right">
	<li><a href="http://twitter.com/log4php/" class="external">Follow <strong>@log4php</strong></a></li>
	</ul>

	<!-- Google CSE Search Box -->
	<form class="navbar-search pull-right" id="cref" action="http://www.google.com/cse">
	<input type="hidden" name="cref" value="http://logging.apache.org/log4php/cse.xml" />
	<input class="search-query pull-left" type="text" name="q" size="40" placeholder="Search" />
	</form>
	</div>
	</div>
	</div>

	<div class="container-fluid">
	<table class="layout-table">
	<tr>
	<td class="sidebar">
	<div class="well sidebar-nav">
	<ul class="nav nav-list">
	<li class="nav-header"><i class="icon-home"></i>Apache log4php™</li>
	<li class="none">
	<a href="../index.html" title="About">About</a>
	</li>
	<li class="none">
	<a href="../download.html" title="Download">Download</a>
	</li>
	<li class="none">
	<a href="../install.html" title="Install">Install</a>
	</li>
	<li class="none">
	<a href="../changelog.html" title="Changelog">Changelog</a>
	</li>
	</ul>
	<ul class="nav nav-list">
	<li class="nav-header"><i class="icon-book"></i>Documentation</li>
	<li class="none">
	<a href="../quickstart.html" title="Quick start">Quick start</a>
	</li>
	<li class="none">
	<a href="../docs/introduction.html" title="Introduction">Introduction</a>
	</li>
	<li class="none active">
	<a href="../docs/configuration.html" title="Configuration">Configuration</a>
	</li>
	<li class="none">
	<a href="../docs/loggers.html" title="Loggers">Loggers</a>
	</li>
	<li class="collapsed">
	<a href="../docs/appenders.html" title="Appenders">Appenders</a>
	</li>
	<li class="collapsed">
	<a href="../docs/layouts.html" title="Layouts">Layouts</a>
	</li>
	<li class="none">
	<a href="../docs/filters.html" title="Filters">Filters</a>
	</li>
	<li class="none">
	<a href="../docs/renderers.html" title="Renderers">Renderers</a>
	</li>
	<li class="none">
	<a href="../apidocs/index.html" title="API documentation">API documentation</a>
	</li>
	</ul>
	<ul class="nav nav-list">
	<li class="nav-header"><i class="icon-user"></i>Community</li>
	<li class="none">
	<a href="../volunteering.html" title="Volunteering">Volunteering</a>
	</li>
	<li class="none">
	<a href="../contributingpatches.html" title="Contributing Patches">Contributing Patches</a>
	</li>
	<li class="none">


	<a href="http://wiki.apache.org/logging-log4php" class="external" target="_blank" title="Wiki">Wiki</a>
	</li>
	<li class="none">


	<a href="http://blogs.apache.org/logging/" class="external" target="_blank" title="Blog">Blog</a>
	</li>
	</ul>
	<ul class="nav nav-list">
	<li class="nav-header"><i class="icon-info-sign"></i>Project Information</li>
	<li class="none">
	<a href="../integration.html" title="Continuous Integration">Continuous Integration</a>
	</li>
	<li class="none">
	<a href="../source-repository.html" title="Source Repository">Source Repository</a>
	</li>
	<li class="none">
	<a href="../dependencies.html" title="Dependencies">Dependencies</a>
	</li>
	<li class="none">
	<a href="../license.html" title="Project License">Project License</a>
	</li>
	<li class="none">
	<a href="../team-list.html" title="Project Team">Project Team</a>
	</li>
	<li class="none">
	<a href="../issue-tracking.html" title="Issue Tracking">Issue Tracking</a>
	</li>
	<li class="none">
	<a href="../mail-lists.html" title="Mailing Lists">Mailing Lists</a>
	</li>
	</ul>
	<ul class="nav nav-list">
	<li class="nav-header"><i class="icon-cog"></i>Project Reports</li>
	<li class="none">
	<a href="../changes-report.html" title="Changes Report">Changes Report</a>
	</li>
	<li class="none">
	<a href="../surefire-report.html" title="Surefire Report">Surefire Report</a>
	</li>
	<li class="none">
	<a href="../rat-report.html" title="RAT Report">RAT Report</a>
	</li>
	<li class="none">
	<a href="../coverage-report/index.html" title="Code Coverage">Code Coverage</a>
	</li>
	</ul>
	<ul class="nav nav-list">
	<li class="nav-header"><i class="icon-heart"></i>Apache</li>
	<li class="none">


	<a href="http://www.apache.org" class="external" target="_blank" title="Home">Home</a>
	</li>
	<li class="none">


	<a href="http://www.apache.org/foundation/sponsorship.html" class="external" target="_blank" title="Sponsorship">Sponsorship</a>
	</li>
	<li class="none">


	<a href="http://www.apache.org/licenses/" class="external" target="_blank" title="License">License</a>
	</li>
	<li class="none">


	<a href="http://www.apache.org/foundation/thanks.html" class="external" target="_blank" title="Thanks">Thanks</a>
	</li>
	<li class="none">


	<a href="http://www.apachecon.com" class="external" target="_blank" title="Conferences">Conferences</a>
	</li>
	<li class="none">


	<a href="http://www.apache.org/security/" class="external" target="_blank" title="Security">Security</a>
	</li>
	</ul>
	</div>
	<div id="poweredBy">
	<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
	<img class="poweredBy" alt="Built by Maven" src="../images/logos/maven-feather.png" />
	</a>
	</div>
	</td>
	<td class="content">
	<!-- 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. -->


	<div class="section"><h2>Configuration<a name="Configuration"></a></h2>

	<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 <tt>Logger::configure()</tt>
	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>

	<a name="XML"></a><div class="section" id="XML"><h3>XML<a name="XML"></a></h3>

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

	<div><pre class="prettyprint linenums">
	<?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></div>

	<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>
	</div>

	<a name="PHP"></a><div class="section" id="PHP"><h3>PHP<a name="PHP"></a></h3>

	<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 <tt>Logger::configure()</tt>.</p>

	<div><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></div>

	<p>Alternatively a file can be created which holds the PHP configuration array. The file must
	have the <tt>php</tt> extension and it should <i>return</i> the configuration array. For example,
	a file named <tt>config.php</tt> with the following content:</p>

	<div><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></div>

	<p>This file can then be used to configure log4php:</p>

	<div><pre class="prettyprint">Logger::configure('config.php');</pre></div>

	<div class="alert alert-info">
	<p><b>Hint:</b> to translate a XML or properties configuration file to PHP, run the following code:</p>
	<div><pre class="prettyprint">
	$configurator = new LoggerConfiguratorDefault();
	$config = $configurator->parse('/path/to/config.xml');
	</pre></div>
	</div>
	</div>


	<a name="INI"></a><div class="section" id="INI"><h3>Properties (INI)<a name="Properties_INI"></a></h3>

	<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 <tt>log4php</tt> instead of <tt>log4j</tt>.</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>


	<div><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></div>
	</div>

	<a name="Default_configuration"></a><div class="section" id="Default_configuration"><h3>Default configuration<a name="Default_configuration"></a></h3>
	<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 <tt>LoggerAppenderEcho</tt> appender,
	using <tt>LoggerLayoutSimple</tt>, attached to the root logger and set to the DEBUG level.</p>

	<p>The default configuration in PHP format is:</p>

	<div><pre class="prettyprint linenums">
	array(
	'rootLogger' => array(
	'appenders' => array('default'),
	),
	'appenders' => array(
	'default' => array(
	'class' => 'LoggerAppenderConsole',
	'layout' => array(
	'class' => 'LoggerLayoutSimple'
	)
	)
	)
	)
	</pre></div>

	<div class="alert alert-info">
	<p><b>Hint:</b> You can fetch the default configuration as a PHP array by running:</p>
	<div><pre class="prettyprint">LoggerConfiguratorDefault::getDefaultConfiguration();</pre></div>
	</div>
	</div>

	<div class="section"><h3>Programmatic configuration<a name="Programmatic_configuration"></a></h3>

	<p>It is possible to configure log4php fully programmatically. This requires the user to implement
	their own configurator object. Configurators must implement the <tt>LoggerConfigurator</tt>
	interface.</p>

	<p>Here is an example:</p>

	<div><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></div>

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

	<div><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>
	<div class="alert alert-warning">
	<p><b>Note: </b>Always call <tt>activateOptions()</tt> on all appenders, filters and layouts after setting
	their configuration parameters. Otherwise, the configuration may not be properly activated.</p>
	</div>
	</div>
	</div>


	</td>
	</tr>
	</table>
	</div>

	<div class="footer">
	<p>Copyright © 2012
	<a href="http://www.apache.org">Apache Software Foundation</a>.
	All Rights Reserved.

	Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache Software License, Version 2.0</a>.
	Please read the <a href="../privacy.html">Privacy policy</a></p>
	<p>Apache log4php, Apache, log4php, the Apache feather logo, the Apache Logging Services project logo and the Built by
	Maven logo are trademarks of The Apache Software Foundation.</p>
	<p>Site powered by <a class="external" href="http://twitter.github.com/bootstrap/">Twitter Bootstrap</a>. Icons from
	<a class="external" href="http://glyphicons.com/">Glyphicons Free</a>.</p>
	</div>
	</body>
	</html>