remapping.xml revision 13e125c14cbafff43783b7f3aed11de6d4cb5b14
3726777f47ac4bba3e21b075905959bbea47e72eerikabele<!DOCTYPE manualpage SYSTEM "/style/manualpage.dtd">
3726777f47ac4bba3e21b075905959bbea47e72eerikabele<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
3726777f47ac4bba3e21b075905959bbea47e72eerikabele<!-- $LastChangedRevision: 832069 $ -->
3726777f47ac4bba3e21b075905959bbea47e72eerikabele Licensed to the Apache Software Foundation (ASF) under one or more
3726777f47ac4bba3e21b075905959bbea47e72eerikabele contributor license agreements. See the NOTICE file distributed with
3726777f47ac4bba3e21b075905959bbea47e72eerikabele this work for additional information regarding copyright ownership.
3726777f47ac4bba3e21b075905959bbea47e72eerikabele The ASF licenses this file to You under the Apache License, Version 2.0
3726777f47ac4bba3e21b075905959bbea47e72eerikabele (the "License"); you may not use this file except in compliance with
3726777f47ac4bba3e21b075905959bbea47e72eerikabele the License. You may obtain a copy of the License at
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd Unless required by applicable law or agreed to in writing, software
3726777f47ac4bba3e21b075905959bbea47e72eerikabele distributed under the License is distributed on an "AS IS" BASIS,
3726777f47ac4bba3e21b075905959bbea47e72eerikabele WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
3726777f47ac4bba3e21b075905959bbea47e72eerikabele See the License for the specific language governing permissions and
4489f0b54d190e8ac29906e1071bbad6c49de17end limitations under the License.
3726777f47ac4bba3e21b075905959bbea47e72eerikabele <parentdocument href="./">Rewrite</parentdocument>
3726777f47ac4bba3e21b075905959bbea47e72eerikabele<p>This document supplements the <module>mod_rewrite</module>
4489f0b54d190e8ac29906e1071bbad6c49de17end<a href="/mod_rewrite.html">reference documentation</a>. It describes
4489f0b54d190e8ac29906e1071bbad6c49de17endhow you can use <module>mod_rewrite</module> to redirect and remap
4489f0b54d190e8ac29906e1071bbad6c49de17endrequest. This includes many examples of common uses of mod_rewrite,
4489f0b54d190e8ac29906e1071bbad6c49de17endincluding detailed descriptions of how each works.</p>
4489f0b54d190e8ac29906e1071bbad6c49de17end<note type="warning">Note that many of these examples won't work unchanged in your
4489f0b54d190e8ac29906e1071bbad6c49de17endparticular server configuration, so it's important that you understand
4489f0b54d190e8ac29906e1071bbad6c49de17endthem, rather than merely cutting and pasting the examples into your
4489f0b54d190e8ac29906e1071bbad6c49de17endconfiguration.</note>
4489f0b54d190e8ac29906e1071bbad6c49de17end<seealso><a href="/mod/mod_rewrite.html">Module documentation</a></seealso>
4489f0b54d190e8ac29906e1071bbad6c49de17end<seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
4489f0b54d190e8ac29906e1071bbad6c49de17end <p>Assume we have recently renamed the page
4489f0b54d190e8ac29906e1071bbad6c49de17end <code>foo.html</code> to <code>bar.html</code> and now want
4489f0b54d190e8ac29906e1071bbad6c49de17end to provide the old URL for backward compatibility. However,
4489f0b54d190e8ac29906e1071bbad6c49de17end we want that users of the old URL even not recognize that
4489f0b54d190e8ac29906e1071bbad6c49de17end the pages was renamed - that is, we don't want the address to
4489f0b54d190e8ac29906e1071bbad6c49de17end change in their browser.</p>
4489f0b54d190e8ac29906e1071bbad6c49de17end <p>We rewrite the old URL to the new one internally via the
4489f0b54d190e8ac29906e1071bbad6c49de17end following rule:</p>
4489f0b54d190e8ac29906e1071bbad6c49de17endRewriteEngine on
4489f0b54d190e8ac29906e1071bbad6c49de17endRewriteRule ^<strong>/old</strong>\.html$ <strong>/new</strong>.html [PT]
e0471b26427a7310358a7a3a835bd146072e4c29nd <p>Assume again that we have recently renamed the page
e0471b26427a7310358a7a3a835bd146072e4c29nd <code>foo.html</code> to <code>bar.html</code> and now want
e0471b26427a7310358a7a3a835bd146072e4c29nd to provide the old URL for backward compatibility. But this
3c56725151a46fef84ce376d709b5339da28e10fnd time we want that the users of the old URL get hinted to
3726777f47ac4bba3e21b075905959bbea47e72eerikabele the new one, i.e. their browsers Location field should
3726777f47ac4bba3e21b075905959bbea47e72eerikabele change, too.</p>
3c56725151a46fef84ce376d709b5339da28e10fnd <p>We force a HTTP redirect to the new URL which leads to a
3c56725151a46fef84ce376d709b5339da28e10fnd change of the browsers and thus the users view:</p>
3726777f47ac4bba3e21b075905959bbea47e72eerikabeleRewriteEngine on
e0471b26427a7310358a7a3a835bd146072e4c29ndRewriteRule ^<strong>/foo</strong>\.html$ <strong>bar</strong>.html [<strong>R</strong>]
3c56725151a46fef84ce376d709b5339da28e10fnd href="#old-to-new-intern">internal</a> example above, we can simply
3c56725151a46fef84ce376d709b5339da28e10fnd use the Redirect directive. mod_rewrite was used in that earlier
3c56725151a46fef84ce376d709b5339da28e10fnd example in order to hide the redirect from the client:</p>
4489f0b54d190e8ac29906e1071bbad6c49de17end </example>
4489f0b54d190e8ac29906e1071bbad6c49de17end <p>How can we transform a static page
4489f0b54d190e8ac29906e1071bbad6c49de17end <code>foo.cgi</code> in a seamless way, i.e. without notice
4489f0b54d190e8ac29906e1071bbad6c49de17end <p>We just rewrite the URL to the CGI-script and force the
4489f0b54d190e8ac29906e1071bbad6c49de17end executed as a CGI program.
4489f0b54d190e8ac29906e1071bbad6c49de17end internally leads to the invocation of
e0471b26427a7310358a7a3a835bd146072e4c29ndRewriteEngine on
e0471b26427a7310358a7a3a835bd146072e4c29ndRewriteBase /~quux/
e0471b26427a7310358a7a3a835bd146072e4c29ndRewriteRule ^foo\.<strong>html</strong>$ foo.<strong>cgi</strong> [H=<strong>cgi-script</strong>]
e0471b26427a7310358a7a3a835bd146072e4c29nd <title>Backward Compatibility for file extension change</title>
3726777f47ac4bba3e21b075905959bbea47e72eerikabele <p>How can we make URLs backward compatible (still
e0471b26427a7310358a7a3a835bd146072e4c29nd existing virtually) after migrating <code>document.YYYY</code>
e0471b26427a7310358a7a3a835bd146072e4c29nd bunch of <code>.html</code> files to <code>.php</code>?</p>
3726777f47ac4bba3e21b075905959bbea47e72eerikabele <p>We rewrite the name to its basename and test for
3726777f47ac4bba3e21b075905959bbea47e72eerikabele existence of the new extension. If it exists, we take
3c56725151a46fef84ce376d709b5339da28e10fnd that name, else we rewrite the URL to its original state.</p>
3726777f47ac4bba3e21b075905959bbea47e72eerikabele# backward compatibility ruleset for
3c56725151a46fef84ce376d709b5339da28e10fnd# when and only when document.php exists
3c56725151a46fef84ce376d709b5339da28e10fndRewriteEngine on
e0471b26427a7310358a7a3a835bd146072e4c29ndRewriteCond $1.php -f
3726777f47ac4bba3e21b075905959bbea47e72eerikabeleRewriteCond $1.html !-f
e0471b26427a7310358a7a3a835bd146072e4c29ndRewriteRule ^(.*).html$ $1.php
3c56725151a46fef84ce376d709b5339da28e10fnd <p>This example uses an often-overlooked feature of mod_rewrite,
e0471b26427a7310358a7a3a835bd146072e4c29nd by taking advantage of the order of execution of the ruleset. In
e0471b26427a7310358a7a3a835bd146072e4c29nd particular, mod_rewrite evaluates the left-hand-side of the
e0471b26427a7310358a7a3a835bd146072e4c29nd RewriteRule before it evaluates the RewriteCond directives.
e0471b26427a7310358a7a3a835bd146072e4c29nd Consequently, $1 is already defined by the time the RewriteRule
e0471b26427a7310358a7a3a835bd146072e4c29nd directives are evaluated. This allows us to test for the existence
e0471b26427a7310358a7a3a835bd146072e4c29nd of the the original (<code>document.html</code>) and target
e0471b26427a7310358a7a3a835bd146072e4c29nd (<code>document.php</code>) files using the same base filename.</p>
e0471b26427a7310358a7a3a835bd146072e4c29nd<section id="canonicalhost"><title>Canonical Hostnames</title>
3c56725151a46fef84ce376d709b5339da28e10fnd <dd>The goal of this rule is to force the use of a particular
3c56725151a46fef84ce376d709b5339da28e10fnd hostname, in preference to other hostnames which may be used to
e0471b26427a7310358a7a3a835bd146072e4c29nd reach the same site. For example, if you wish to force the use
4489f0b54d190e8ac29906e1071bbad6c49de17end <strong>example.com</strong>, you might use a variant of the
4489f0b54d190e8ac29906e1071bbad6c49de17end following recipe.</dd>
e0471b26427a7310358a7a3a835bd146072e4c29ndRewriteCond %{HTTP_HOST} !^www\.example\.com [NC]
e0471b26427a7310358a7a3a835bd146072e4c29ndRewriteCond %{HTTP_HOST} !^$
e0471b26427a7310358a7a3a835bd146072e4c29ndRewriteCond %{SERVER_PORT} !^80$
3726777f47ac4bba3e21b075905959bbea47e72eerikabeleRewriteRule ^/?(.*) http://www.example.com:%{SERVER_PORT}/$1 [L,R,NE]
e0471b26427a7310358a7a3a835bd146072e4c29ndRewriteCond %{HTTP_HOST} !^www\.example\.com [NC]
e0471b26427a7310358a7a3a835bd146072e4c29ndRewriteCond %{HTTP_HOST} !^$
e0471b26427a7310358a7a3a835bd146072e4c29ndRewriteRule ^/?(.*) http://www.example.com/$1 [L,R,NE]
e0471b26427a7310358a7a3a835bd146072e4c29nd If you wanted to do this generically for all domain names - that
e0471b26427a7310358a7a3a835bd146072e4c29nd is, if you want to redirect <strong>example.com</strong> to
e0471b26427a7310358a7a3a835bd146072e4c29nd <strong>www.example.com</strong> for all possible values of
e0471b26427a7310358a7a3a835bd146072e4c29nd <strong>example.com</strong>, you could use the following
e0471b26427a7310358a7a3a835bd146072e4c29nd recipe:</p>
e0471b26427a7310358a7a3a835bd146072e4c29ndRewriteCond %{HTTP_HOST} !^www\. [NC]
e0471b26427a7310358a7a3a835bd146072e4c29ndRewriteCond %{HTTP_HOST} !^$
e0471b26427a7310358a7a3a835bd146072e4c29ndRewriteRule ^/?(.*) http://www.%{HTTP_HOST}/$1 [L,R,NE]
e0471b26427a7310358a7a3a835bd146072e4c29nd <p>These rulesets will work either in your main server configuration
e0471b26427a7310358a7a3a835bd146072e4c29nd file, or in a <code>.htaccess</code> file placed in the <directive
e0471b26427a7310358a7a3a835bd146072e4c29nd module="core">DocumentRoot</directive> of the server.</p>
e0471b26427a7310358a7a3a835bd146072e4c29nd <title>Search for pages in more than one directory</title>
e0471b26427a7310358a7a3a835bd146072e4c29nd <p>A particular resource might exist in one of several places, and
e0471b26427a7310358a7a3a835bd146072e4c29nd we want to look in those places for the resource when it is
e0471b26427a7310358a7a3a835bd146072e4c29nd requested. Perhaps we've recently rearranged our directory
e0471b26427a7310358a7a3a835bd146072e4c29nd structure, dividing content into several locations.</p>
e0471b26427a7310358a7a3a835bd146072e4c29nd <p>The following ruleset searches in two directories to find the
e0471b26427a7310358a7a3a835bd146072e4c29nd resource, and, if not finding it in either place, will attempt to
e0471b26427a7310358a7a3a835bd146072e4c29nd just serve it out of the location requested.</p>
e0471b26427a7310358a7a3a835bd146072e4c29ndRewriteEngine on
e0471b26427a7310358a7a3a835bd146072e4c29nd# first try to find it in dir1/...
e0471b26427a7310358a7a3a835bd146072e4c29nd# ...and if found stop and be happy:
e0471b26427a7310358a7a3a835bd146072e4c29ndRewriteCond %{DOCUMENT_ROOT}/<strong>dir1</strong>/%{REQUEST_URI} -f
e0471b26427a7310358a7a3a835bd146072e4c29ndRewriteRule ^(.+) %{DOCUMENT_ROOT}/<strong>dir1</strong>/$1 [L]
e0471b26427a7310358a7a3a835bd146072e4c29nd# second try to find it in dir2/...
e0471b26427a7310358a7a3a835bd146072e4c29nd# ...and if found stop and be happy:
e0471b26427a7310358a7a3a835bd146072e4c29ndRewriteCond %{DOCUMENT_ROOT}/<strong>dir2</strong>/%{REQUEST_URI} -f
4489f0b54d190e8ac29906e1071bbad6c49de17endRewriteRule ^(.+) %{DOCUMENT_ROOT}/<strong>dir2</strong>/$1 [L]
e0471b26427a7310358a7a3a835bd146072e4c29nd# else go on for other Alias or ScriptAlias directives,
e0471b26427a7310358a7a3a835bd146072e4c29ndRewriteRule ^(.+) - [PT]
e0471b26427a7310358a7a3a835bd146072e4c29nd</manualpage>