<li><img alt="" src="../images/down.gif" /> <a href="#smart">Smart Filtering</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#terms">Filter Declarations, Providers and Chains</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#config">Configuring the Chain</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#upgrade">Upgrading from HTTPD 2.2 Configuration</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#protocol">Protocol Handling</a></li>
</ul></div>
declare it with the default type AP_FTYPE_RESOURCE. The provider
must have been
registered with <code>ap_register_output_filter</code> by some module.
- The remaining arguments to <code class="directive"><a href="#filterprovider">FilterProvider</a></code> are a dispatch criterion and a match string.
- The former may be an HTTP request or response header, an environment
- variable, or the Handler used by this request. The latter is matched
- to it for each request, to determine whether this provider will be
- used to implement the filter for this request.</dd>
+ The final argument to <code class="directive"><a href="#filterprovider">FilterProvider</a></code> is an expression: the provider will be
+ selected to run for a request if and only if the expression evaluates
+ to true. The expression may evaluate HTTP request or response
+ headers, environment variables, or the Handler used by this request.
+ Unlike earlier versions, mod_filter now supports complex expressions
+ involving multiple criteria with AND / OR logic (&& / ||)
+ and brackets.</dd>
<dt>Configure the Chain</dt>
<dd>The above directives build components of a smart filter chain,
</dl>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
+<h2><a name="upgrade" id="upgrade">Upgrading from HTTPD 2.2 Configuration</a></h2>
+ <p>The <code class="directive"><a href="#filterprovider">FilterProvider</a></code>
+ directive has changed from HTTPD 2.2: the <var>match</var> and
+ <var>dispatch</var> arguments are replaced with a single but
+ more versatile <var>expression</var>. In general, you can convert
+ a match/dispatch pair to the two sides of an expression, using
+ something like:</p>
+ <div class="example"><p><code>"dispatch = match"</code></p></div>
+ <p>The Request headers, Response headers and Environment variables
+ are now interpreted from syntax <var>$req{foo}</var>,
+ <var>$resp{foo}</var> and <var>$env{foo}</var> respectively.
+ The variables <var>$handler</var> and <var>$Content-Type</var>
+ are also supported.</p>
+ <p>Note that the match no longer supports integer comparisons
+ or substring matches. The latter can be replaced by regular
+ expression matches.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
<h2><a name="examples" id="examples">Examples</a></h2>
<dl>
<dt>Server side Includes (SSI)</dt>
<code class="directive"><a href="../mod/core.html#addoutputfilterbytype">AddOutputFilterByType</a></code>
<div class="example"><p><code>
FilterDeclare SSI<br />
- FilterProvider SSI INCLUDES resp=Content-Type $text/html<br />
+ FilterProvider SSI INCLUDES "$resp{Content-Type} = /^text\/html/"<br />
FilterChain SSI
</code></p></div>
</dd>
<dd>The same as the above but dispatching on handler (classic
SSI behaviour; .shtml files get processed).
<div class="example"><p><code>
- FilterProvider SSI INCLUDES Handler server-parsed<br />
+ FilterProvider SSI INCLUDES "Handler = server-parsed"<br />
FilterChain SSI
</code></p></div>
</dd>
Accept-Encoding header. This filter runs with ftype CONTENT_SET.
<div class="example"><p><code>
FilterDeclare gzip CONTENT_SET<br />
- FilterProvider gzip inflate req=Accept-Encoding !$gzip<br />
+ FilterProvider gzip inflate "$req{Accept-Encoding} != /gzip/"<br />
FilterChain gzip
</code></p></div>
</dd>
<dd>Suppose we want to downsample all web images, and have filters
for GIF, JPEG and PNG.
<div class="example"><p><code>
- FilterProvider unpack jpeg_unpack Content-Type $image/jpeg<br />
- FilterProvider unpack gif_unpack Content-Type $image/gif<br />
- FilterProvider unpack png_unpack Content-Type $image/png<br />
+ FilterProvider unpack jpeg_unpack "$resp{Content-Type} = image/jpeg"<br />
+ FilterProvider unpack gif_unpack "$resp{Content-Type} = image/gif"<br />
+ FilterProvider unpack png_unpack "$resp{Content-Type} = image/png"<br />
<br />
- FilterProvider downsample downsample_filter Content-Type $image<br />
+ FilterProvider downsample downsample_filter "$resp{Content-Type} = /image\/(jpeg|gif|png)/"<br />
FilterProtocol downsample "change=yes"<br />
<br />
- FilterProvider repack jpeg_pack Content-Type $image/jpeg<br />
- FilterProvider repack gif_pack Content-Type $image/gif<br />
- FilterProvider repack png_pack Content-Type $image/png<br />
+ FilterProvider repack jpeg_pack "$resp{Content-Type} = image/jpeg"<br />
+ FilterProvider repack gif_pack "$resp{Content-Type} = image/gif"<br />
+ FilterProvider repack png_pack "$resp{Content-Type} = image/png"<br />
<Location /image-filter><br />
<span class="indent">
FilterChain unpack downsample repack<br />
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Register a content filter</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterProvider <var>filter-name</var> <var>provider-name</var>
- [req|resp|env]=<var>dispatch</var> <var>match</var></code></td></tr>
+ <var>expression</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr>
</table>
<p>This directive registers a <em>provider</em> for the smart filter.
- The provider will be called if and only if the <var>match</var> declared
- here matches the value of the header or environment variable declared
- as <var>dispatch</var>.</p>
+ The provider will be called if and only if the <var>expression</var>
+ declared evaluates to true when the harness is first called.</p>
<p>
<var>provider-name</var> must have been registered by loading
a module that registers the name with
<code>ap_register_output_filter</code>.
-
</p>
- <p>The <var>dispatch</var> argument is a string with optional
- <code>req=</code>, <code>resp=</code> or <code>env=</code> prefix
- causing it to dispatch on (respectively) the request header, response
- header, or environment variable named. In the absence of a
- prefix, it defaults to a response header. A special case is the
- word <code>handler</code>, which causes <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code>
- to dispatch on the content handler.</p>
-
- <p>The <var>match</var> argument specifies a match that will be applied to
- the filter's <var>dispatch</var> criterion. The <var>match</var> may be
- a string match (exact match or substring), a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regex</a>, an integer (greater, lessthan or equals), or
- unconditional. The first characters of the <var>match</var> argument
- determines this:</p>
-
- <p><strong>First</strong>, if the first character is an exclamation mark
- (<code>!</code>), this reverses the rule, so the provider will be used
- if and only if the match <em>fails</em>.</p>
-
- <p><strong>Second</strong>, it interprets the first character excluding
- any leading <code>!</code> as follows:</p>
-
- <table class="bordered"><tr class="header"><th>Character</th><th>Description</th></tr>
-<tr><td><em>(none)</em></td><td>exact match</td></tr>
-<tr class="odd"><td><code>$</code></td><td>substring match</td></tr>
-<tr><td><code>/</code></td><td>regex match (delimited by a second <code>/</code>)</td></tr>
-<tr class="odd"><td><code>=</code></td><td>integer equality</td></tr>
-<tr><td><code><</code></td><td>integer less-than</td></tr>
-<tr class="odd"><td><code><=</code></td><td>integer less-than or equal</td></tr>
-<tr><td><code>></code></td><td>integer greater-than</td></tr>
-<tr class="odd"><td><code>>=</code></td><td>integer greater-than or equal</td></tr>
-<tr><td><code>*</code></td><td>Unconditional match</td></tr>
-</table>
+ <p><var>expression</var> can be any of the following:</p>
+ <dl>
+ <dt><code><var>string</var></code></dt>
+ <dd>true if <var>string</var> is not empty</dd>
+
+ <dt><code><var>string1</var> = <var>string2</var><br />
+ <var>string1</var> == <var>string2</var><br />
+ <var>string1</var> != <var>string2</var></code></dt>
+
+ <dd><p>Compare <var>string1</var> with <var>string2</var>. If
+ <var>string2</var> has the form <code>/<var>string2</var>/</code>
+ then it is treated as a regular expression. Regular expressions are
+ implemented by the <a href="http://www.pcre.org">PCRE</a> engine and
+ have the same syntax as those in <a href="http://www.perl.com">perl
+ 5</a>. Note that <code>==</code> is just an alias for <code>=</code>
+ and behaves exactly the same way.</p>
+ </dd>
+
+ <dt><code><var>string1</var> < <var>string2</var><br />
+ <var>string1</var> <= <var>string2</var><br />
+ <var>string1</var> > <var>string2</var><br />
+ <var>string1</var> >= <var>string2</var></code></dt>
+
+ <dd>Compare <var>string1</var> with <var>string2</var>. Note, that
+ strings are compared <em>literally</em> (using
+ <code>strcmp(3)</code>). Therefore the string "100" is less than
+ "20".</dd>
+
+ <dt><code>( <var>expression</var> )</code></dt>
+ <dd>true if <var>expression</var> is true</dd>
+
+ <dt><code>! <var>expression</var></code></dt>
+ <dd>true if <var>expression</var> is false</dd>
+
+ <dt><code><var>expression1</var> &&
+ <var>expression2</var></code></dt>
+ <dd>true if both <var>expression1</var> and
+ <var>expression2</var> are true</dd>
+
+ <dt><code><var>expression1</var> ||
+ <var>expression2</var></code></dt>
+ <dd>true if either <var>expression1</var> or
+ <var>expression2</var> is true</dd>
+ </dl>
+
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
projects / apache / commitdiff