content/log4php/2.3.0/docs/filters.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 -
 		Filters - 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">
 								<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 active">
 								<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>Filters<a name="Filters"></a></h2>

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

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

 			<ol style="list-style-type: decimal">
 				<li><b>ACCEPT</b> the logging event - The event will be logged without consulting the
 				remaining filters in the chain.</li>
 				<li><b>DENY</b> the logging event - The event will be not logged without consulting the
 				remaining filters in the chain.</li>
 				<li>Remain <b>NEUTRAL</b> - 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.</li>
 			</ol>

 			<a name="Configuring_filters"></a><div class="section" id="Configuring_filters"><h3>Configuring filters<a name="Configuring_filters"></a></h3>

 				<p>Filters are configurable in the XML and PHP configuration format. They cannot be configured using
 				the properties configuration format.</p>

 				<p>Like appenders and layouts, depending on the class used, filters may have configurable parameters
 				which determine their behaviour.</p>

 				<p>Here is a configuration example:</p>

 				<div class="auto-tabs">
 					<ul>
 						<li>XML</li>
 						<li>PHP</li>
 					</ul>

 					<div class="tab-content">
 						<div class="tab-pane">
 <div><pre class="prettyprint linenums">
 &lt;configuration xmlns=&quot;http://logging.apache.org/log4php/&quot;&gt;
     &lt;appender name=&quot;defualt&quot; class=&quot;LoggerAppenderEcho&quot;&gt;
         &lt;layout class=&quot;LoggerLayoutSimple&quot;/&gt;
         &lt;filter class=&quot;LoggerFilterStringMatch&quot;&gt;
             &lt;param name=&quot;stringToMatch&quot; value=&quot;interesting&quot; /&gt;
             &lt;param name=&quot;acceptOnMatch&quot; value=&quot;true&quot; /&gt;
         &lt;/filter&gt;
         &lt;filter class=&quot;LoggerFilterLevelRange&quot;&gt;
             &lt;param name=&quot;levelMin&quot; value=&quot;debug&quot; /&gt;
             &lt;param name=&quot;levelMax&quot; value=&quot;error&quot; /&gt;
         &lt;/filter&gt;
     &lt;/appender&gt;
     &lt;root&gt;
         &lt;level value=&quot;TRACE&quot; /&gt;
         &lt;appender_ref ref=&quot;defualt&quot; /&gt;
     &lt;/root&gt;
 &lt;/configuration&gt;
 </pre></div>

 						</div>
 						<div class="tab-pane">
 <div><pre class="prettyprint linenums">
 array(
     'appenders' =&gt; array(
         'default' =&gt; array(
             'class' =&gt; 'LoggerAppenderEcho'
             'layout' =&gt; array(
                 'class' =&gt; 'LoggerLayoutSimple'
             ),
             'filters' =&gt; array(
                 array(
                     'class' =&gt; 'LoggerFilterStringMatch',
                     'params' =&gt; array(
                         'stringToMatch' =&gt; 'interesting',
                         'acceptOnMatch' =&gt; true,
                     )
                 ),
                 array(
                     'class' =&gt; 'LoggerFilterLevelRange',
                     'params' =&gt; array(
                         'levelMin' =&gt; 'debug',
                         'levelMax' =&gt; 'error',
                     )
                 )
             )
         )
     ),
     'rootLogger' =&gt; array(
     	'appenders' =&gt; array('default'),
     )
 )
 </pre></div>
 						</div>
 					</div>
 				</div>

 				<p>In this example, there are two filters defined for the <i>default</i> appender.</p>

 				<p>The first filter <tt>LoggerFilterStringMatch</tt> searches for the string &quot;interesting&quot; 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.</p>

 				<p>The second filter <tt>LoggerFilterLevelRange</tt> 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.</p>

 				<p>Therefore, this filter configuration will log events which which have a level between DEBUG and
 				ERROR, except of theose which have the string &quot;interesting&quot; in the message. Those will be logged
 				regardless of their level.</p>

 			</div>

 			<div class="section"><h3>Filter reference<a name="Filter_reference"></a></h3>

 				<p>The following filters are available in log4php:</p>

 				<table border="0" class="bodyTable">
 					<thead>
 						<tr class="a">
 							<th>Name</th>
 							<th>Destination</th>
 						</tr>
 					</thead>
 					<tbody>
 						<tr class="b">
 							<td><a href="#LoggerFilterDenyAll">LoggerFilterDenyAll</a></td>
 							<td>Denies all logging events.</td>
 						</tr>
 						<tr class="a">
 							<td><a href="#LoggerFilterLevelMatch">LoggerFilterLevelMatch</a></td>
 							<td>Filters based on logging event level.</td>
 						</tr>
 						<tr class="b">
 							<td><a href="#LoggerFilterLevelRange">LoggerFilterLevelRange</a></td>
 							<td>Filters based on logging event level range.</td>
 						</tr>
 						<tr class="a">
 							<td><a href="#LoggerFilterStringMatch">LoggerFilterStringMatch</a></td>
 							<td>Filters by searching for a string in the logging event message.</td>
 						</tr>
 					</tbody>
 				</table>
 			</div>


 			<a name="LoggerFilterDenyAll"></a><div class="section" id="LoggerFilterDenyAll"><h3>LoggerFilterDenyAll<a name="LoggerFilterDenyAll"></a></h3>
 				<p>This filters simply denies all logging events. It has no configurable parameters.</p>
 			</div>

 			<a name="LoggerFilterLevelMatch"></a><div class="section" id="LoggerFilterLevelMatch"><h3>LoggerFilterLevelMatch<a name="LoggerFilterLevelMatch"></a></h3>
 				<p>This filter either accepts the specified logger level or denies it.</p>

 				<div class="section"><h4>Configurable parameters<a name="Configurable_parameters"></a></h4>

 				<table border="0" class="bodyTable">
 					<thead>
 						<tr class="a">
 							<th>Parameter</th>
 							<th>Type</th>
 							<th>Required</th>
 							<th>Default</th>
 							<th>Description</th>
 						</tr>
 					</thead>
 					<tbody>
 						<tr class="b">
 							<td>levelToMatch</td>
 							<td>LoggerLevel</td>
 							<td><b>Yes</b></td>
 							<td>-</td>
 							<td>The level to match</td>
 						</tr>
 						<tr class="a">
 							<td>acceptOnMatch</td>
 							<td>boolean</td>
 							<td>No</td>
 							<td>true</td>
 							<td>If true, the matching log level is accepted, denied otherwise.</td>
 						</tr>
 					</tbody>
 				</table>

 				</div><div class="section"><h4>Example<a name="Example"></a></h4>

 				<p>The following filter configuration will deny all logging events with level DEBUG. It will remain
 				neutral for others.</p>

 <div><pre class="prettyprint linenums">
 &lt;filter class=&quot;LoggerFilterLevelMatch&quot;&gt;
     &lt;param name=&quot;levelToMatch&quot; value=&quot;debug&quot; /&gt;
     &lt;param name=&quot;acceptOnMatch&quot; value=&quot;false&quot; /&gt;
 &lt;/filter&gt;
 </pre></div>

 			</div></div>

 			<a name="LoggerFilterLevelRange"></a><div class="section" id="LoggerFilterLevelRange"><h3>LoggerFilterLevelRange<a name="LoggerFilterLevelRange"></a></h3>
 				<p>This filter accepts or denies logging events if their log level is within the specified range.</p>

 				<div class="section"><h4>Configurable parameters<a name="Configurable_parameters"></a></h4>

 				<table border="0" class="bodyTable">
 					<thead>
 						<tr class="a">
 							<th>Parameter</th>
 							<th>Type</th>
 							<th>Required</th>
 							<th>Default</th>
 							<th>Description</th>
 						</tr>
 					</thead>
 					<tbody>
 						<tr class="b">
 							<td>levelMin</td>
 							<td>LoggerLevel</td>
 							<td><b>Yes</b></td>
 							<td>-</td>
 							<td>The minimum level to log. If set, levels lower than this will be denied.</td>
 						</tr>
 						<tr class="a">
 							<td>levelMax</td>
 							<td>LoggerLevel</td>
 							<td><b>Yes</b></td>
 							<td>-</td>
 							<td>The maximum level to log. If set, levels higher than this will be denied.</td>
 						</tr>
 						<tr class="b">
 							<td>acceptOnMatch</td>
 							<td>boolean</td>
 							<td>No</td>
 							<td>true</td>
 							<td>If true, the matching log level is accepted, denied otherwise.</td>
 						</tr>
 					</tbody>
 				</table>

 				</div><div class="section"><h4>Example<a name="Example"></a></h4>

 				<p>The following filter configuration denies levels greater than WARN.</p>

 <div><pre class="prettyprint linenums">
 &lt;filter class=&quot;LoggerFilterLevelRange&quot;&gt;
     &lt;param name=&quot;levelMax&quot; value=&quot;warn&quot; /&gt;
     &lt;param name=&quot;acceptOnMatch&quot; value=&quot;false&quot; /&gt;
 &lt;/filter&gt;
 </pre></div>

 			</div></div>

 			<a name="LoggerFilterStringMatch"></a><div class="section" id="LoggerFilterStringMatch"><h3>LoggerFilterStringMatch<a name="LoggerFilterStringMatch"></a></h3>
 				<p>This filter allows or denies logging events if their message contains a given string.</p>

 				<div class="section"><h4>Configurable parameters<a name="Configurable_parameters"></a></h4>

 				<table border="0" class="bodyTable">
 					<thead>
 						<tr class="a">
 							<th>Parameter</th>
 							<th>Type</th>
 							<th>Required</th>
 							<th>Default</th>
 							<th>Description</th>
 						</tr>
 					</thead>
 					<tbody>
 						<tr class="b">
 							<td>stringToMatch</td>
 							<td>LoggerLevel</td>
 							<td><b>Yes</b></td>
 							<td>-</td>
 							<td>The level to match</td>
 						</tr>
 						<tr class="a">
 							<td>levelMax</td>
 							<td>LoggerLevel</td>
 							<td><b>Yes</b></td>
 							<td>-</td>
 							<td>The level to match</td>
 						</tr>
 						<tr class="b">
 							<td>acceptOnMatch</td>
 							<td>boolean</td>
 							<td>No</td>
 							<td>true</td>
 							<td>If true, the matching log level is accepted, denied otherwise.</td>
 						</tr>
 					</tbody>
 				</table>

 				</div><div class="section"><h4>Example<a name="Example"></a></h4>

 				<p>The following filter configuration denies events which contain the string &quot;not-interesting&quot; in
 				their message.</p>

 <div><pre class="prettyprint linenums">
 &lt;filter class=&quot;LoggerFilterStringMatch&quot;&gt;
     &lt;param name=&quot;StringToMatch&quot; value=&quot;not-interesting&quot; /&gt;
     &lt;param name=&quot;AcceptOnMatch&quot; value=&quot;false&quot; /&gt;
 &lt;/filter&gt;
 </pre></div>

 			</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 -
	Filters - 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">
	<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 active">
	<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>Filters<a name="Filters"></a></h2>

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

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

	<ol style="list-style-type: decimal">
	<li><b>ACCEPT</b> the logging event - The event will be logged without consulting the
	remaining filters in the chain.</li>
	<li><b>DENY</b> the logging event - The event will be not logged without consulting the
	remaining filters in the chain.</li>
	<li>Remain <b>NEUTRAL</b> - 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.</li>
	</ol>

	<a name="Configuring_filters"></a><div class="section" id="Configuring_filters"><h3>Configuring filters<a name="Configuring_filters"></a></h3>

	<p>Filters are configurable in the XML and PHP configuration format. They cannot be configured using
	the properties configuration format.</p>

	<p>Like appenders and layouts, depending on the class used, filters may have configurable parameters
	which determine their behaviour.</p>

	<p>Here is a configuration example:</p>

	<div class="auto-tabs">
	<ul>
	<li>XML</li>
	<li>PHP</li>
	</ul>

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

	</div>
	<div class="tab-pane">
	<div><pre class="prettyprint linenums">
	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'),
	)
	)
	</pre></div>
	</div>
	</div>
	</div>

	<p>In this example, there are two filters defined for the <i>default</i> appender.</p>

	<p>The first filter <tt>LoggerFilterStringMatch</tt> 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.</p>

	<p>The second filter <tt>LoggerFilterLevelRange</tt> 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.</p>

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

	</div>

	<div class="section"><h3>Filter reference<a name="Filter_reference"></a></h3>

	<p>The following filters are available in log4php:</p>

	<table border="0" class="bodyTable">
	<thead>
	<tr class="a">
	<th>Name</th>
	<th>Destination</th>
	</tr>
	</thead>
	<tbody>
	<tr class="b">
	<td><a href="#LoggerFilterDenyAll">LoggerFilterDenyAll</a></td>
	<td>Denies all logging events.</td>
	</tr>
	<tr class="a">
	<td><a href="#LoggerFilterLevelMatch">LoggerFilterLevelMatch</a></td>
	<td>Filters based on logging event level.</td>
	</tr>
	<tr class="b">
	<td><a href="#LoggerFilterLevelRange">LoggerFilterLevelRange</a></td>
	<td>Filters based on logging event level range.</td>
	</tr>
	<tr class="a">
	<td><a href="#LoggerFilterStringMatch">LoggerFilterStringMatch</a></td>
	<td>Filters by searching for a string in the logging event message.</td>
	</tr>
	</tbody>
	</table>
	</div>


	<a name="LoggerFilterDenyAll"></a><div class="section" id="LoggerFilterDenyAll"><h3>LoggerFilterDenyAll<a name="LoggerFilterDenyAll"></a></h3>
	<p>This filters simply denies all logging events. It has no configurable parameters.</p>
	</div>

	<a name="LoggerFilterLevelMatch"></a><div class="section" id="LoggerFilterLevelMatch"><h3>LoggerFilterLevelMatch<a name="LoggerFilterLevelMatch"></a></h3>
	<p>This filter either accepts the specified logger level or denies it.</p>

	<div class="section"><h4>Configurable parameters<a name="Configurable_parameters"></a></h4>

	<table border="0" class="bodyTable">
	<thead>
	<tr class="a">
	<th>Parameter</th>
	<th>Type</th>
	<th>Required</th>
	<th>Default</th>
	<th>Description</th>
	</tr>
	</thead>
	<tbody>
	<tr class="b">
	<td>levelToMatch</td>
	<td>LoggerLevel</td>
	<td><b>Yes</b></td>
	<td>-</td>
	<td>The level to match</td>
	</tr>
	<tr class="a">
	<td>acceptOnMatch</td>
	<td>boolean</td>
	<td>No</td>
	<td>true</td>
	<td>If true, the matching log level is accepted, denied otherwise.</td>
	</tr>
	</tbody>
	</table>

	</div><div class="section"><h4>Example<a name="Example"></a></h4>

	<p>The following filter configuration will deny all logging events with level DEBUG. It will remain
	neutral for others.</p>

	<div><pre class="prettyprint linenums">
	<filter class="LoggerFilterLevelMatch">
	<param name="levelToMatch" value="debug" />
	<param name="acceptOnMatch" value="false" />
	</filter>
	</pre></div>

	</div></div>

	<a name="LoggerFilterLevelRange"></a><div class="section" id="LoggerFilterLevelRange"><h3>LoggerFilterLevelRange<a name="LoggerFilterLevelRange"></a></h3>
	<p>This filter accepts or denies logging events if their log level is within the specified range.</p>

	<div class="section"><h4>Configurable parameters<a name="Configurable_parameters"></a></h4>

	<table border="0" class="bodyTable">
	<thead>
	<tr class="a">
	<th>Parameter</th>
	<th>Type</th>
	<th>Required</th>
	<th>Default</th>
	<th>Description</th>
	</tr>
	</thead>
	<tbody>
	<tr class="b">
	<td>levelMin</td>
	<td>LoggerLevel</td>
	<td><b>Yes</b></td>
	<td>-</td>
	<td>The minimum level to log. If set, levels lower than this will be denied.</td>
	</tr>
	<tr class="a">
	<td>levelMax</td>
	<td>LoggerLevel</td>
	<td><b>Yes</b></td>
	<td>-</td>
	<td>The maximum level to log. If set, levels higher than this will be denied.</td>
	</tr>
	<tr class="b">
	<td>acceptOnMatch</td>
	<td>boolean</td>
	<td>No</td>
	<td>true</td>
	<td>If true, the matching log level is accepted, denied otherwise.</td>
	</tr>
	</tbody>
	</table>

	</div><div class="section"><h4>Example<a name="Example"></a></h4>

	<p>The following filter configuration denies levels greater than WARN.</p>

	<div><pre class="prettyprint linenums">
	<filter class="LoggerFilterLevelRange">
	<param name="levelMax" value="warn" />
	<param name="acceptOnMatch" value="false" />
	</filter>
	</pre></div>

	</div></div>

	<a name="LoggerFilterStringMatch"></a><div class="section" id="LoggerFilterStringMatch"><h3>LoggerFilterStringMatch<a name="LoggerFilterStringMatch"></a></h3>
	<p>This filter allows or denies logging events if their message contains a given string.</p>

	<div class="section"><h4>Configurable parameters<a name="Configurable_parameters"></a></h4>

	<table border="0" class="bodyTable">
	<thead>
	<tr class="a">
	<th>Parameter</th>
	<th>Type</th>
	<th>Required</th>
	<th>Default</th>
	<th>Description</th>
	</tr>
	</thead>
	<tbody>
	<tr class="b">
	<td>stringToMatch</td>
	<td>LoggerLevel</td>
	<td><b>Yes</b></td>
	<td>-</td>
	<td>The level to match</td>
	</tr>
	<tr class="a">
	<td>levelMax</td>
	<td>LoggerLevel</td>
	<td><b>Yes</b></td>
	<td>-</td>
	<td>The level to match</td>
	</tr>
	<tr class="b">
	<td>acceptOnMatch</td>
	<td>boolean</td>
	<td>No</td>
	<td>true</td>
	<td>If true, the matching log level is accepted, denied otherwise.</td>
	</tr>
	</tbody>
	</table>

	</div><div class="section"><h4>Example<a name="Example"></a></h4>

	<p>The following filter configuration denies events which contain the string "not-interesting" in
	their message.</p>

	<div><pre class="prettyprint linenums">
	<filter class="LoggerFilterStringMatch">
	<param name="StringToMatch" value="not-interesting" />
	<param name="AcceptOnMatch" value="false" />
	</filter>
	</pre></div>

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