granicus.if.org Git - apache/blob - docs/manual/rewrite/rewrite_intro.xml

   1 <?xml version='1.0' encoding='UTF-8' ?>
   2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <manualpage metafile="rewrite_intro.xml.meta">
  24 <parentdocument href="./index.html"/>
  25
  26   <title>Apache mod_rewrite Introduction</title>
  27
  28 <summary>
  29 <p>This document supplements the <module>mod_rewrite</module>
  30 <a href="../mod/mod_rewrite.html">reference documentation</a>. It
  31 describes the basic concepts necessary for use of
  32 <module>mod_rewrite</module>. Other documents go into greater detail,
  33 but this doc should help the beginner get their feet wet.
  34 </p>
  35 </summary>
  36
  37 <seealso><a href="../mod/mod_rewrite.html">Module
  38 documentation</a></seealso>
  39 <seealso><a href="rewrite_tech.html">Technical details</a></seealso>
  40 <seealso><a href="rewrite_guide.html">Practical solutions to common
  41 problems</a></seealso>
  42 <seealso><a href="rewrite_guide_advanced.html">Practical solutions to
  43 advanced problems</a></seealso>
  44
  45 <section id="introduction"><title>Introduction</title>
  46 <p>The Apache module <module>mod_rewrite</module> is a very powerful and
  47 sophisticated module which provides a way to do URL manipulations. With
  48 it, you can do nearly all types of URL rewriting that you may need. It
  49 is, however, somewhat complex, and may be intimidating to the beginner.
  50 There is also a tendency to treat rewrite rules as magic incantation,
  51 using them without actually understanding what they do.</p>
  52
  53 <p>This document attempts to give sufficient background so that what
  54 follows is understood, rather than just copied blindly.
  55 </p>
  56 </section>
  57
  58 <section id="regex"><title>Regular Expressions</title>
  59
  60 <p>mod_rewrite uses the <a href="http://pcre.org/">Perl Compatible
  61 Regular Expression</a> vocabulary. In this document, we do not attempt
  62 to provide a detailed reference to regular expressions. For that, we
  63 recommend the <a href="http://pcre.org/pcre.txt">PCRE man pages</a>, the
  64 <a href="http://perldoc.perl.org/perlre.html">Perl regular
  65 expression man page</a>, and <a
  66 href="http://www.oreilly.com/catalog/regex2/index.html">Mastering
  67 Regular Expressions, by Jeffrey Friedl</a>.</p>
  68
  69 <p>In this document, we attempt to provide enough of a regex vocabulary
  70 to get you started, without being overwhelming, in the hope that
  71 <directive module="mod_rewrite">RewriteRule</directive>s will be scientific
  72 formulae, rather than magical incantations.</p>
  73
  74 <section id="regexvocab"><title>Regex vocabulary</title>
  75
  76 <p>The following are the minimal building blocks you will need, in order
  77 to write regular expressions and <directive
  78 module="mod_rewrite">RewriteRule</directive>s. They certainly do not
  79 represent a complete regular expression vocabulary, but they are a good
  80 place to start, and should help you read basic regular expressions, as
  81 well as write your own.</p>
  82
  83 <table>
  84 <tr>
  85 <th>Character</th>
  86 <th>Meaning</th>
  87 <th>Example</th>
  88 </tr>
  89
  90 <tr><td><code>.</code></td><td>Matches any
  91 character</td><td><code>c.t</code> will match <code>cat</code>,
  92 <code>cot</code>, <code>cut</code>, etc.</td></tr>
  93 <tr><td><code>+</code></td><td>Repeats the previous match one or more
  94 times</td><td><code>a+</code> matches <code>a</code>, <code>aa</code>,
  95 <code>aaa</code>, etc</td></tr>
  96 <tr><td><code>*</code></td><td>Repeats the previous match zero or more
  97 times.</td><td><code>a*</code> matches all the same things
  98 <code>a+</code> matches, but will also match an empty string.</td></tr>
  99 <tr><td><code>?</code></td><td>Makes the match optional.</td><td></td></tr>
 100 <tr><td><code>.</code></td><td>Matches any
 101 character</td><td><code>colou?r</code> will match <code>color</code> and
 102 <code>colour</code>.</td></tr>
 103 <tr><td><code>^</code></td><td>Called an anchor, matches the beginning
 104 of the string</td><td><code>^a</code> matches a string that begins with
 105 <code>a</code></td></tr>
 106 <tr><td><code>$</code></td><td>The other anchor, this matches the end of
 107 the string.</td><td><code>a$</code> matches a string that ends with
 108 <code>a</code>.</td></tr>
 109 <tr><td><code>( )</code></td><td>Groups several characters into a single
 110 unit, and captures a match for use in a backreference.</td><td><code>(ab)+</code>
 111 matches <code>ababab</code> - that is, the <code>+</code> applies to the group.
 112 For more on backreferences see <a href="#InternalBackRefs">below</a>.</td></tr>
 113 <tr><td><code>[ ]</code></td><td>A character class - matches one of the
 114 characters</td><td><code>c[uoa]t</code> matches <code>cut</code>,
 115 <code>cot</code> or <code>cat</code>.</td></tr>
 116 <tr><td><code>!</code></td><td>Not</td><td>Negates a match - that is,
 117 ensures that it does not match.</td></tr>
 118
 119 </table>
 120
 121 </section>
 122
 123 <section id="InternalBackRefs"><title>Regex Back-Reference Availability</title>
 124
 125       <p>One important thing here has to be remembered: Whenever you
 126       use parentheses in <em>Pattern</em> or in one of the
 127       <em>CondPattern</em>, back-references are internally created
 128       which can be used with the strings <code>$N</code> and
 129       <code>%N</code> (see below). These are available for creating
 130       the strings <em>Substitution</em> and <em>TestString</em>.
 131       Figure 2 shows to which locations the back-references are
 132       transferred for expansion.</p>
 133
 134 <p class="figure">
 135       <img src="../images/mod_rewrite_fig2.gif" width="381"
 136            height="179" alt="[Needs graphics capability to display]" /><br />
 137       <dfn>Figure 2:</dfn> The back-reference flow through a rule.
 138 </p>
 139
 140 </section>
 141 </section>
 142
 143 <section id="rewriterule"><title>RewriteRule basics</title>
 144 <p>
 145 Basic anatomy of a RewriteRule, with exhaustively annotated simple
 146 examples.
 147 </p>
 148 </section>
 149
 150 <section id="flags"><title>Rewrite Flags</title>
 151 <p>The behavior of a <directive
 152 module="mod_rewrite">RewriteRule</directive> can be modified by the
 153 application of one more flags to the end of the rule. For example, the
 154 matching behavior of a rule can be made case-insensitive by the
 155 application of the <code>[NC]</code> flag:
 156 </p>
 157 <example>
 158 RewriteRule ^puppy.html smalldog.html [NC]
 159 </example>
 160
 161 <p>For more details on the available flags, their meanings, and
 162 examples, see the <a href="flags.html">Rewrite Flags</a> document.</p>
 163
 164 </section>
 165
 166
 167 <section id="rewritecond"><title>Rewrite conditions</title>
 168 <p>The <directive module="mod_rewrite">RewriteCond</directive> directive
 169 allows a condition to be applied to a <directive
 170 module="mod_rewrite">RewriteRule</directive>.
 171 </p>
 172
 173 </section>
 174
 175 <section id="rewritemap"><title>Rewrite maps</title>
 176 <p>Discussion of RewriteMap, including simple, but heavily annotated,
 177 examples.</p>
 178 </section>
 179
 180 <section id="htaccess"><title>.htaccess files</title>
 181 <p>Discussion of the differences between rewrite rules in httpd.conf and
 182 in .htaccess files.</p>
 183 </section>
 184
 185 <section id="EnvVar"><title>Environment Variables</title>
 186
 187 <p>This module keeps track of two additional (non-standard)
 188 CGI/SSI environment variables named <code>SCRIPT_URL</code>
 189 and <code>SCRIPT_URI</code>. These contain the
 190 <em>logical</em> Web-view to the current resource, while the
 191 standard CGI/SSI variables <code>SCRIPT_NAME</code> and
 192 <code>SCRIPT_FILENAME</code> contain the <em>physical</em>
 193 System-view. </p>
 194
 195 <p>Notice: These variables hold the URI/URL <em>as they were
 196 initially requested</em>, <em>i.e.</em>, <em>before</em> any
 197 rewriting. This is important because the rewriting process is
 198 primarily used to rewrite logical URLs to physical
 199 pathnames.</p>
 200
 201 <example><title>Example</title>
 202 <pre>
 203 SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
 204 SCRIPT_FILENAME=/u/rse/.www/index.html
 205 SCRIPT_URL=/u/rse/
 206 SCRIPT_URI=http://en1.engelschall.com/u/rse/
 207 </pre>
 208 </example>
 209
 210 </section>
 211
 212 </manualpage>
 213