tech.html.en revision 75607c055fdc81f37f672648693dc512ac7478f6
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe This file is generated from xml source: DO NOT EDIT
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe<title>Apache mod_rewrite Technical Details - Apache HTTP Server</title>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe<link href="/images/favicon.ico" rel="shortcut icon" /></head>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe<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>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe<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> > <a href="./">Rewrite</a></div><div id="page-content"><div id="preamble"><h1>Apache mod_rewrite Technical Details</h1>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe<p><span>Available Languages: </span><a href="/en/rewrite/tech.html" title="English"> en </a> |
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe<a href="/fr/rewrite/tech.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe<p>This document discusses some of the technical details of mod_rewrite
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawroweand URL matching.</p>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#InternalAPI">API Phases</a></li>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe<li><img alt="" src="/images/down.gif" /> <a href="#InternalRuleset">Ruleset Processing</a></li>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe</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="rewritemap.html">Using RewriteMap</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>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe<h2><a name="InternalAPI" id="InternalAPI">API Phases</a></h2>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe <p>The Apache HTTP Server handles requests in several phases. At
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe each of these phases, one or more modules may be called upon to
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe handle that portion of the request lifecycle. Phases include things
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe like URL-to-filename translation, authentication, authorization,
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe content, and logging. (This is not an exhaustive list.)</p>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe <p>mod_rewrite acts in two of these phases (or "hooks", as they are
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe often called) to influence how URLs may be rewritten.</p>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe <p>First, it uses the URL-to-filename translation hook, which occurs
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe after the HTTP request has been read, but before any authorization
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe starts. Secondly, it uses the Fixup hook, which is after the
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe authorization phases, and after per-directory configuration files
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe (<code>.htaccess</code> files) have been read, but before the
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe content handler is called.</p>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe <p>So, after a request comes in and a corresponding server or
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe virtual host has been determined, the rewriting engine starts
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe processing any <code>mod_rewrite</code> directives appearing in the
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe per-server configuration. (i.e., in the main server configuration file
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe and <code class="directive"><a href="/mod/core.html#virtualhost"><Virtualhost></a></code>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe sections.) This happens in the URL-to-filename phase.</p>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe <p>A few steps later, once the final data directories have been found,
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe the per-directory configuration directives (<code>.htaccess</code>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe files and <code class="directive"><a href="/mod/core.html#directory"><Directory></a></code> blocks) are applied. This
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe happens in the Fixup phase.</p>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe <p>In each of these cases, mod_rewrite rewrites the
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe <code>REQUEST_URI</code> either to a new URL, or to a filename.</p>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe <p>In per-directory context (i.e., within <code>.htaccess</code> files
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe and <code>Directory</code> blocks), these rules are being applied
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe after a URL has already been translated to a filename. Because of
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe this, the URL-path that mod_rewrite initially compares <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directives against
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe is the full filesystem path to the translated filename with the current
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe directories path (including a trailing slash) removed from the front.</p>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe <p> To illustrate: If rules are in /var/www/foo/.htaccess and a request
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe for /foo/bar/baz is being processed, an expression like ^bar/baz$ would
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe <p> If a substitution is made in per-directory context, a new internal
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe subrequest is issued with the new URL, which restarts processing of the
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe request phases. If the substitution is a relative path, the <code class="directive"><a href="/mod/mod_rewrite.html#rewritebase">RewriteBase</a></code> directive
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe determines the URL-path prefix prepended to the substitution.
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe In per-directory context, care must be taken to
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe create rules which will eventually (in some future "round" of per-directory
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe rewrite processing) not perform a substitution to avoid looping.
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe (See <a href="http://wiki.apache.org/httpd/RewriteLooping">RewriteLooping</a>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe for further discussion of this problem.)</p>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe <p>Because of this further manipulation of the URL in per-directory
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe context, you'll need to take care to craft your rewrite rules
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe differently in that context. In particular, remember that the
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe leading directory path will be stripped off of the URL that your
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe rewrite rules will see. Consider the examples below for further
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe clarification.</p>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe <td>RewriteRule ^/images/(.+)\.jpg /images/$1.gif</td>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe <p>For even more insight into how mod_rewrite manipulates URLs in
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe different contexts, you should consult the <a href="/mod/mod_rewrite.html#logging">log entries</a> made during
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe rewriting.</p>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe<h2><a name="InternalRuleset" id="InternalRuleset">Ruleset Processing</a></h2>
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe <p>Now when mod_rewrite is triggered in these two API phases, it
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe reads the configured rulesets from its configuration
f01ac228d6d88fcc7a466fc9c1152e2e40ff17cawrowe structure (which itself was either created on startup for
through the ruleset rule by rule (<code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directives) and
<img src="/images/rewrite_rule_flow.png" alt="Flow of RewriteRule and RewriteCond matching" /><br />
<p><span>Available Languages: </span><a href="/en/rewrite/tech.html" title="English"> en </a> |
<a href="/fr/rewrite/tech.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p>
<p class="apache">Copyright 2011 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>