diff options
Diffstat (limited to 'docs/manual')
| -rw-r--r-- | docs/manual/rewrite/tech.xml | 146 |
1 files changed, 73 insertions, 73 deletions
diff --git a/docs/manual/rewrite/tech.xml b/docs/manual/rewrite/tech.xml index 27c6aea548..5aa5408cba 100644 --- a/docs/manual/rewrite/tech.xml +++ b/docs/manual/rewrite/tech.xml @@ -39,81 +39,81 @@ and URL matching.</p> <seealso><a href="advanced.html">Advanced techniques</a></seealso> <seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso> -<section id="Internal"><title>Internal Processing</title> - - <p>The internal processing of this module is very complex but - needs to be explained once even to the average user to avoid - common mistakes and to let you exploit its full - functionality.</p> -</section> - <section id="InternalAPI"><title>API Phases</title> - <p>First you have to understand that when Apache processes a - HTTP request it does this in phases. A hook for each of these - phases is provided by the Apache API. Mod_rewrite uses two of - these hooks: the URL-to-filename translation hook which is - used after the HTTP request has been read but before any - authorization starts and the Fixup hook which is triggered - after the authorization phases and after the per-directory - config files (<code>.htaccess</code>) have been read, but - before the content handler is activated.</p> - - <p>So, after a request comes in and Apache has determined the - corresponding server (or virtual server) the rewriting engine - starts processing of all mod_rewrite directives from the - per-server configuration in the URL-to-filename phase. A few - steps later when the final data directories are found, the - per-directory configuration directives of mod_rewrite are - triggered in the Fixup phase. In both situations mod_rewrite - rewrites URLs either to new URLs or to filenames, although - there is no obvious distinction between them. This is a usage - of the API which was not intended to be this way when the API - was designed, but as of Apache 1.x this is the only way - mod_rewrite can operate. To make this point more clear - remember the following two points:</p> - - <ol> - <li>Although mod_rewrite rewrites URLs to URLs, URLs to - filenames and even filenames to filenames, the API - currently provides only a URL-to-filename hook. In Apache - 2.0 the two missing hooks will be added to make the - processing more clear. But this point has no drawbacks for - the user, it is just a fact which should be remembered: - Apache does more in the URL-to-filename hook than the API - intends for it.</li> - - <li> - Unbelievably mod_rewrite provides URL manipulations in - per-directory context, <em>i.e.</em>, within - <code>.htaccess</code> files, although these are reached - a very long time after the URLs have been translated to - filenames. It has to be this way because - <code>.htaccess</code> files live in the filesystem, so - processing has already reached this stage. In other - words: According to the API phases at this time it is too - late for any URL manipulations. To overcome this chicken - and egg problem mod_rewrite uses a trick: When you - manipulate a URL/filename in per-directory context - mod_rewrite first rewrites the filename back to its - corresponding URL (which is usually impossible, but see - the <code>RewriteBase</code> directive below for the - trick to achieve this) and then initiates a new internal - sub-request with the new URL. This restarts processing of - the API phases. - - <p>Again mod_rewrite tries hard to make this complicated - step totally transparent to the user, but you should - remember here: While URL manipulations in per-server - context are really fast and efficient, per-directory - rewrites are slow and inefficient due to this chicken and - egg problem. But on the other hand this is the only way - mod_rewrite can provide (locally restricted) URL - manipulations to the average user.</p> - </li> - </ol> - - <p>Don't forget these two points!</p> + <p>The Apache HTTP Server handles requests in several phases. At + each of these phases, one or more modules may be called upon to + handle that portion of the request lifecycle. Phases include things + like URL-to-filename translation, authentication, authorization, + content, and logging. (These is not an exhaustive list.)</p> + + <p>mod_rewrite acts in two of these phases (or "hooks", as they are + sometimes called) to influence how URLs may be rewritten.</p> + + <p>First, it uses the URL-to-filename translation hook, which occurs + after the HTTP request has been read, but before any authorization + starts. Secondly, it uses the Fixup hook, which is after the + authorizatin phases, and after per-directory configuration files + (<code>.htaccess</code> files) have been read, but before the + content handler is called.</p> + + <p>So, after a request comes in and a corresponding server or + virtual host has been determined, the rewriting engine starts + processing any <code>mod_rewrite</code> directives appearing in the + per-server configuration. (ie, in the main server configuration file + and <directive module="core" type="section">Virtualhost</directive> + sections.) This happens in the URL-to-filename phase.</p> + + <p>A few steps later, when the finaly data directories are found, + the per-directory configuration directives (<code>.htaccess</code> + files and <directive module="core" + type="section">Directory</directive> blocks) are applied. This + happens in the Fixup phase.</p> + + <p>In each of these cases, mod_rewrite rewrites the + <code>REQUEST_URI</code> either to a new URI, or to a filename.</p> + + <p>In per-directory context (ie, within <code>.htaccess</code> files + and <code>Directory</code> blocks), these rules are being applied + after a URI has already been translated to a filename. Because of + this, mod_rewrite temporarily translates the filename back into a URI, + by stripping off directory paty before appling the rules. (See the + <directive module="mod_rewrite">RewriteBase</directive> directive to + see how you can further manipulate how this is handled.) Then, a new + internal subrequest is issued with the new URI. This restarts + processing of the API phases.</p> + + <p>Because of this further manipulation of the URI in per-directory + context, you'll need to take care to craft your rewrite rules + differently in that context. In particular, remember that the + leading directory path will be stripped off of the URI that your + rewrite rules will see. Consider the examples below for further + clarification.</p> + + <table border="1"> + + <tr> + <th>Location of rule</th> + <th>Rule</th> + </tr> + + <tr> + <td>VirtualHost section</td> + <td>RewriteRule ^/images/(.+)\.jpg /images/$1.gif</td> + </tr> + + <tr> + <td>.htaccess file in document root</td> + <td>RewriteRule ^images/(.+)\.jpg images/$1.gif</td> + </tr> + + <tr> + <td>.htaccess file in images directory</td> + <td>RewriteRule ^(.+)\.jpg $1.gif</td> + </tr> + + </table> + </section> <section id="InternalRuleset"><title>Ruleset Processing</title> |