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