rewritemap.html.en revision 4bf04ac5fe6a2ae518bd0d8d463f069253d46c0a
97a9a944b5887e91042b019776c41d5dd74557aferikabele<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
97a9a944b5887e91042b019776c41d5dd74557aferikabele<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
a945f35eff8b6a88009ce73de6d4c862ce58de3cslive XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
a945f35eff8b6a88009ce73de6d4c862ce58de3cslive This file is generated from xml source: DO NOT EDIT
a945f35eff8b6a88009ce73de6d4c862ce58de3cslive XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
96ad5d81ee4a2cc66a4ae19893efc8aa6d06fae7jailletc<title>Using RewriteMap - Apache HTTP Server</title>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
2e545ce2450a9953665f701bb05350f0d3f26275nd<link href="/images/favicon.ico" rel="shortcut icon" /></head>
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
3f08db06526d6901aa08c110b5bc7dde6bc39905nd<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.5</a> > <a href="./">Rewrite</a></div><div id="page-content"><div id="preamble"><h1>Using RewriteMap</h1>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<p><span>Available Languages: </span><a href="/en/rewrite/rewritemap.html" title="English"> en </a></p>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd <p>This document supplements the <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code>
3b3b7fc78d1f5bfc2769903375050048ff41ff26nd<a href="/mod/mod_rewrite.html">reference documentation</a>. It describes
ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7ndthe use of the <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive,
660c7c6d7e175238807ffc144c0f8e746bf2cfb0minfrinand provides examples of each of the various <code>RewriteMap</code> types.</p>
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung <div class="warning">Note that many of these examples won't work unchanged in your
3b3b7fc78d1f5bfc2769903375050048ff41ff26ndparticular server configuration, so it's important that you understand
fe64b2ba25510d8c9dba5560a2d537763566cf40ndthem, rather than merely cutting and pasting the examples into your
fe64b2ba25510d8c9dba5560a2d537763566cf40ndconfiguration.</div>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#introduction">Introduction</a></li>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<li><img alt="" src="/images/down.gif" /> <a href="#txt">txt: Plain text maps</a></li>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<li><img alt="" src="/images/down.gif" /> <a href="#rnd">rnd: Randomized Plain Text</a></li>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<li><img alt="" src="/images/down.gif" /> <a href="#dbm">dbm: DBM Hash File</a></li>
97a9a944b5887e91042b019776c41d5dd74557aferikabele<li><img alt="" src="/images/down.gif" /> <a href="#int">int: Internal Function</a></li>
f67d046f3809f2659fa2b9842ca17ff87a1f01c4nd<li><img alt="" src="/images/down.gif" /> <a href="#prg">prg: External Rewriting Program</a></li>
f67d046f3809f2659fa2b9842ca17ff87a1f01c4nd<li><img alt="" src="/images/down.gif" /> <a href="#dbd">dbd or fastdbd: SQL Query</a></li>
f67d046f3809f2659fa2b9842ca17ff87a1f01c4nd<li><img alt="" src="/images/down.gif" /> <a href="#summary">Summary</a></li>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive</ul><h3>See also</h3><ul class="seealso"><li><a href="/mod/mod_rewrite.html">Module documentation</a></li><li><a href="intro.html">mod_rewrite introduction</a></li><li><a href="remapping.html">Redirection and remapping</a></li><li><a href="access.html">Controlling access</a></li><li><a href="vhosts.html">Virtual hosts</a></li><li><a href="proxy.html">Proxying</a></li><li><a href="advanced.html">Advanced techniques</a></li><li><a href="avoid.html">When not to use mod_rewrite</a></li></ul></div>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<h2><a name="introduction" id="introduction">Introduction</a></h2>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive The <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive
06ba4a61654b3763ad65f52283832ebf058fdf1cslive defines an external function which can be called in the context of
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> or
136489fb8f0fe36dbcad3064a335eb86bfbeb5c6rbowen <code class="directive"><a href="/mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> directives to
97a9a944b5887e91042b019776c41d5dd74557aferikabele perform rewriting that is too complicated, or too specialized to be
06ba4a61654b3763ad65f52283832ebf058fdf1cslive performed just by regular expressions. The source of this lookup can
06ba4a61654b3763ad65f52283832ebf058fdf1cslive be any of the types listed in the sections below, and enumerated in
97a9a944b5887e91042b019776c41d5dd74557aferikabele the <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> reference
06ba4a61654b3763ad65f52283832ebf058fdf1cslive documentation.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>The syntax of the <code>RewriteMap</code> directive is as
fe64b2ba25510d8c9dba5560a2d537763566cf40nd follows:</p>
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjortonRewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is an
117c1f888a14e73cdd821dc6c23eb0411144a41cnd arbitray name that you assign to the map, and which you will use in
fe64b2ba25510d8c9dba5560a2d537763566cf40nd directives later on. Arguments are passed to the map via the
fe64b2ba25510d8c9dba5560a2d537763566cf40nd following syntax:</p>
9bcfc3697a91b5215893a7d0206865b13fc72148nd <code>${</code> <em>MapName</em> <code>:</code> <em>LookupKey</em>
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh <code>}</code> <br /> <code>${</code> <em>MapName</em> <code>:</code>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar <em>LookupKey</em> <code>|</code> <em>DefaultValue</em> <code>}</code>
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton <p>When such a construct occurs, the map <em>MapName</em> is
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton consulted and the key <em>LookupKey</em> is looked-up. If the
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton key is found, the map-function construct is substituted by
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar <em>SubstValue</em>. If the key is not found then it is
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton substituted by <em>DefaultValue</em> or by the empty string
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton <p>For example, you might define a
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar <p>You would then be able to use this map in a
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton <code class="directive">RewriteRule</code> as follows:</p>
20f499565e77defe9dab24dd85c02f38a1175855nd RewriteRule ^/ex/(.*) ${examplemap:$1}
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton<p>A default value can be specified in the event that nothing is found
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjortonin the map:</p>
fe64b2ba25510d8c9dba5560a2d537763566cf40ndRewriteRule ^/ex/(.*) ${examplemap:$1|/not_found.html}
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<div class="note"><h3>Per-directory and .htaccess context</h3>
3ffe84681ed8add175b7b33f1985d9db941eccaftrawickThe <code>RewriteMap</code> directive may not be used in
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<Directory> sections or <code>.htaccess</code> files. You must
fe64b2ba25510d8c9dba5560a2d537763566cf40nddeclare the map in server or virtualhost context. You may use the map,
75241911a05371c31eb43e91cd40645a905408cccolm<code>RewriteCond</code> directives in those scopes. You just can't
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<p>The sections that follow describe the various <em>MapType</em>s that
06ba4a61654b3763ad65f52283832ebf058fdf1cslivemay be used, and give examples of each.</p>
f2c4476994729750806eaa70d8b55fa2b3eba25brbowen </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar<h2><a name="txt" id="txt">txt: Plain text maps</a></h2>
20f499565e77defe9dab24dd85c02f38a1175855nd <p>When a MapType of <code>txt</code> is used, the MapSource is a filesystem path to a
e487d6c09669296f94a5190cc34586a98e624a00nd plain-text mapping file, containing space-separated key/value pair
f2c4476994729750806eaa70d8b55fa2b3eba25brbowen per line. Optionally, a line may be contain a comment, starting with
fe64b2ba25510d8c9dba5560a2d537763566cf40nd a '#' character.</p>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd <p>For example, the following might be valid entries in a map
7f5b59ccc63c0c0e3e678a168f09ee6a2f51f9d0nd # Comment line<br />
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung <strong><em>MatchingKey</em> <em>SubstValue</em></strong><br />
727872d18412fc021f03969b8641810d8896820bhumbedooh <strong><em>MatchingKey</em> <em>SubstValue</em></strong> # comment<br />
cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedooh <p>When the RewriteMap is invoked the argument is looked for in the
0d0ba3a410038e179b695446bb149cce6264e0abnd first argument of a line, and, if found, the substitution value is
cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedooh returned.</p>
0d0ba3a410038e179b695446bb149cce6264e0abnd <p>For example, we might use a mapfile to translate product names to
0d0ba3a410038e179b695446bb149cce6264e0abnd product IDs for easier-to-remember URLs, using the following
0d0ba3a410038e179b695446bb149cce6264e0abnd recipe:</p>
0d0ba3a410038e179b695446bb149cce6264e0abnd <div class="example"><h3>Product to ID configuration</h3><p><code>
0d0ba3a410038e179b695446bb149cce6264e0abnd RewriteMap product2id txt:/etc/apache2/productmap.txt<br />
0d0ba3a410038e179b695446bb149cce6264e0abnd RewriteRule ^/product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
0d0ba3a410038e179b695446bb149cce6264e0abnd <p>We assume here that the <code>prods.php</code> script knows what
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh to do when it received an argument of <code>id=NOTFOUND</code> when
205f749042ed530040a4f0080dbcb47ceae8a374rjung a product is not found in the lookup map.</p>
0d0ba3a410038e179b695446bb149cce6264e0abnd <p>The file <code>/etc/apache2/productmap.txt</code> then contains
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd the following:</p>
RewriteRule ^product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
However, it is recommended that you just use the <a href="/programs/httxt2dbm.html">httxt2dbm</a> utility that is
a context that does not have <code class="directive"><a href="/mod/mod_rewrite.html#rewriteengine">RewriteEngine</a></code> set to
<p><code class="module"><a href="/mod/mod_dbd.html">mod_dbd</a></code> will need to be configured to point at
<p><span>Available Languages: </span><a href="/en/rewrite/rewritemap.html" title="English"> en </a></p>
<p class="apache">Copyright 2012 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div>