rewrite_intro.html.en revision 8c44fe1bc3c69c843dc48f744e062cc4422e7726
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
This file is generated from xml source: DO NOT EDIT
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-->
<title>Apache mod_rewrite Introduction - Apache HTTP Server</title>
<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
<body id="manual-page"><div id="page-header">
<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>
<p class="apache">Apache HTTP Server Version 2.3</p>
<div class="up"><a href="/index.html"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
<div id="path">
<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.3</a></div><div id="page-content"><div id="preamble"><h1>Apache mod_rewrite Introduction</h1>
<div class="toplang">
<p><span>Available Languages: </span><a href="/en/rewrite/rewrite_intro.html" title="English"> en </a></p>
</div>
<p>This document supplements the <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code>
describes the basic concepts necessary for use of
<code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code>. Other documents go into greater detail,
but this doc should help the beginner get their feet wet.
</p>
</div>
<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#introduction">Introduction</a></li>
documentation</a></li><li><a href="rewrite_tech.html">Technical details</a></li><li><a href="rewrite_guide.html">Practical solutions to common
advanced problems</a></li></ul></div>
<div class="section">
<h2><a name="introduction" id="introduction">Introduction</a></h2>
<p>The Apache module <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code> is a very powerful and
sophisticated module which provides a way to do URL manipulations. With
it, you can do nearly all types of URL rewriting that you may need. It
is, however, somewhat complex, and may be intimidating to the beginner.
There is also a tendency to treat rewrite rules as magic incantation,
using them without actually understanding what they do.</p>
<p>This document attempts to give sufficient background so that what
follows is understood, rather than just copied blindly.
</p>
<div class="section">
<h2><a name="regex" id="regex">Regular Expressions</a></h2>
Regular Expression</a> vocabulary. In this document, we do not attempt
to provide a detailed reference to regular expressions. For that, we
<a href="http://perldoc.perl.org/perlre.html">Perl regular
Regular Expressions, by Jeffrey Friedl</a>.</p>
<p>In this document, we attempt to provide enough of a regex vocabulary
to get you started, without being overwhelming, in the hope that
<code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>s will be scientific
formulae, rather than magical incantations.</p>
<h3><a name="regexvocab" id="regexvocab">Regex vocabulary</a></h3>
<p>The following are the minimal building blocks you will need, in order
to write regular expressions and <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>s. They certainly do not
represent a complete regular expression vocabulary, but they are a good
place to start, and should help you read basic regular expressions, as
well as write your own.</p>
<table>
<tr>
<th>Character</th>
<th>Meaning</th>
<th>Example</th>
</tr>
<tr><td><code>.</code></td><td>Matches any
<code>cot</code>, <code>cut</code>, etc.</td></tr>
<tr><td><code>+</code></td><td>Repeats the previous match one or more
times</td><td><code>a+</code> matches <code>a</code>, <code>aa</code>,
<code>aaa</code>, etc</td></tr>
<tr><td><code>*</code></td><td>Repeats the previous match zero or more
times.</td><td><code>a*</code> matches all the same things
<code>a+</code> matches, but will also match an empty string.</td></tr>
<tr><td><code>?</code></td><td>Makes the match optional.</td><td /></tr>
<tr><td><code>.</code></td><td>Matches any
character</td><td><code>colou?r</code> will match <code>color</code> and
<code>colour</code>.</td></tr>
<tr><td><code>^</code></td><td>Called an anchor, matches the beginning
of the string</td><td><code>^a</code> matches a string that begins with
<code>a</code></td></tr>
<tr><td><code>$</code></td><td>The other anchor, this matches the end of
the string.</td><td><code>a$</code> matches a string that ends with
<code>a</code>.</td></tr>
<tr><td><code>( )</code></td><td>Groups several characters into a single
unit, and captures a match for use in a backreference.</td><td><code>(ab)+</code>
matches <code>ababab</code> - that is, the <code>+</code> applies to the group.
For more on backreferences see <a href="#InternalBackRefs">below</a>.</td></tr>
<tr><td><code>[ ]</code></td><td>A character class - matches one of the
characters</td><td><code>c[uoa]t</code> matches <code>cut</code>,
<code>cot</code> or <code>cat</code>.</td></tr>
<tr><td><code>!</code></td><td>Not</td><td>Negates a match - that is,
ensures that it does not match.</td></tr>
</table>
<h3><a name="InternalBackRefs" id="InternalBackRefs">Regex Back-Reference Availability</a></h3>
<p>One important thing here has to be remembered: Whenever you
use parentheses in <em>Pattern</em> or in one of the
<em>CondPattern</em>, back-references are internally created
which can be used with the strings <code>$N</code> and
<code>%N</code> (see below). These are available for creating
the strings <em>Substitution</em> and <em>TestString</em>.
Figure 2 shows to which locations the back-references are
transferred for expansion.</p>
<p class="figure">
<img src="/images/mod_rewrite_fig2.gif" width="381" height="179" alt="[Needs graphics capability to display]" /><br />
<dfn>Figure 2:</dfn> The back-reference flow through a rule.
</p>
<div class="section">
<h2><a name="rewriterule" id="rewriterule">RewriteRule basics</a></h2>
<p>
Basic anatomy of a RewriteRule, with exhaustively annotated simple
examples.
</p>
<div class="section">
<h2><a name="flags" id="flags">Rewrite Flags</a></h2>
<p>The behavior of a <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> can be modified by the
application of one more flags to the end of the rule. For example, the
matching behavior of a rule can be made case-insensitive by the
application of the <code>[NC]</code> flag:
</p>
<div class="example"><p><code>
RewriteRule ^puppy.html smalldog.html [NC]
</code></p></div>
<p>For more details on the available flags, their meanings, and
<div class="section">
<h2><a name="rewritecond" id="rewritecond">Rewrite conditions</a></h2>
<p>The <code class="directive"><a href="/mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> directive
allows a condition to be applied to a <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>.
</p>
<div class="section">
<h2><a name="rewritemap" id="rewritemap">Rewrite maps</a></h2>
<p>Discussion of RewriteMap, including simple, but heavily annotated,
examples.</p>
<div class="section">
<h2><a name="htaccess" id="htaccess">.htaccess files</a></h2>
<p>Discussion of the differences between rewrite rules in httpd.conf and
in .htaccess files.</p>
<div class="section">
<h2><a name="EnvVar" id="EnvVar">Environment Variables</a></h2>
<p>This module keeps track of two additional (non-standard)
and <code>SCRIPT_URI</code>. These contain the
<em>logical</em> Web-view to the current resource, while the
<code>SCRIPT_FILENAME</code> contain the <em>physical</em>
System-view. </p>
rewriting. This is important because the rewriting process is
primarily used to rewrite logical URLs to physical
pathnames.</p>
<div class="example"><h3>Example</h3><pre>
SCRIPT_URI=http://en1.engelschall.com/u/rse/
</pre></div>
</div></div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="/en/rewrite/rewrite_intro.html" title="English"> en </a></p>
</div><div id="footer">
<p class="apache">Copyright 2007 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>
</body></html>