File: rewrite_intro.html.en

package info (click to toggle)
apache2 2.2.3-4%2Betch11
  • links: PTS
  • area: main
  • in suites: etch
  • size: 35,160 kB
  • ctags: 19,065
  • sloc: ansic: 206,618; sh: 18,457; perl: 1,649; makefile: 1,103; awk: 874; pascal: 490; python: 308; lex: 191; yacc: 100
file content (196 lines) | stat: -rw-r--r-- 11,137 bytes parent folder | download | duplicates (2) 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
 
<?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">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
        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" />
<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
<link href="../images/favicon.ico" rel="shortcut icon" /></head>
<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.2</p>
<img alt="" src="../images/feather.gif" /></div>
<div class="up"><a href="./index.html"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
<div id="path">
<a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.2</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">&nbsp;en&nbsp;</a></p>
</div>

<p>This document supplements the <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
<a href="../mod/mod_rewrite.html">reference documentation</a>. It
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>
<li><img alt="" src="../images/down.gif" /> <a href="#regex">Regular Expressions</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#rewriterule">RewriteRule basics</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#flags">Rewrite Flags</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#rewritecond">Rewrite conditions</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#rewritemap">Rewrite maps</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#htaccess">.htaccess files</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#EnvVar">Environment Variables</a></li>
</ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module
documentation</a></li><li><a href="rewrite_tech.html">Technical details</a></li><li><a href="rewrite_guide.html">Practical solutions to common
problems</a></li><li><a href="rewrite_guide_advanced.html">Practical solutions to
advanced problems</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></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><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="regex" id="regex">Regular Expressions</a></h2>

<p>mod_rewrite uses the <a href="http://pcre.org/">Perl Compatible
Regular Expression</a> vocabulary. In this document, we do not attempt
to provide a detailed reference to regular expressions. For that, we
recommend the <a href="http://pcre.org/pcre.txt">PCRE man pages</a>, the
<a href="http://www.perldoc.com/perl5.8.0/pod/perlre.html">Perl regular
expression man page</a>, and <a href="http://www.oreilly.com/catalog/regex2/index.html">Mastering
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
character</td><td><code>c.t</code> will match <code>cat</code>,
<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><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<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><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="flags" id="flags">Rewrite Flags</a></h2>
<p>Discussion of the flags to RewriteRule, and when and why one might
use them.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="rewritecond" id="rewritecond">Rewrite conditions</a></h2>
<p>Discussion of RewriteCond, looping, and other related concepts.
</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<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><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<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><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="EnvVar" id="EnvVar">Environment Variables</a></h2>

<p>This module keeps track of two additional (non-standard)
CGI/SSI environment variables named <code>SCRIPT_URL</code>
and <code>SCRIPT_URI</code>. These contain the
<em>logical</em> Web-view to the current resource, while the
standard CGI/SSI variables <code>SCRIPT_NAME</code> and
<code>SCRIPT_FILENAME</code> contain the <em>physical</em>
System-view. </p>

<p>Notice: These variables hold the URI/URL <em>as they were
initially requested</em>, <em>i.e.</em>, <em>before</em> any
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_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
SCRIPT_FILENAME=/u/rse/.www/index.html
SCRIPT_URL=/u/rse/
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">&nbsp;en&nbsp;</a></p>
</div><div id="footer">
<p class="apache">Copyright 2006 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>