You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by rb...@apache.org on 2026/05/14 19:17:28 UTC

svn commit: r1934198 - httpd/httpd/trunk/docs/manual/rewrite

Author: rbowen
Date: Thu May 14 19:17:27 2026
New Revision: 1934198

Log:
rewrite guide: document mod_rewrite vs mod_alias processing order

tech.xml: new "Module Processing Order" section explaining that
mod_rewrite runs before mod_alias in server/vhost context (hook
priority, not config order), and that per-directory context reverses
this. Includes a concrete example and practical guidance.

avoid.xml: add cross-reference note to the "Simple Redirection"
section warning about the order inconsistency.

Modified:
   httpd/httpd/trunk/docs/manual/rewrite/TODO.md
   httpd/httpd/trunk/docs/manual/rewrite/avoid.xml
   httpd/httpd/trunk/docs/manual/rewrite/tech.xml

Modified: httpd/httpd/trunk/docs/manual/rewrite/TODO.md
==============================================================================
--- httpd/httpd/trunk/docs/manual/rewrite/TODO.md	Thu May 14 17:09:54 2026	(r1934197)
+++ httpd/httpd/trunk/docs/manual/rewrite/TODO.md	Thu May 14 19:17:27 2026	(r1934198)
@@ -56,7 +56,7 @@ address. Sorted by priority.
 
 ### HIGH — Widely asked, not covered
 
-- [ ] **Redirect vs. RewriteRule processing order** — mod_rewrite runs
+- [x] **Redirect vs. RewriteRule processing order** — mod_rewrite runs
       *before* mod_alias regardless of config file order. Mixing them
       in the same context confuses users every year. Belongs in avoid.xml
       or tech.xml.

Modified: httpd/httpd/trunk/docs/manual/rewrite/avoid.xml
==============================================================================
--- httpd/httpd/trunk/docs/manual/rewrite/avoid.xml	Thu May 14 17:09:54 2026	(r1934197)
+++ httpd/httpd/trunk/docs/manual/rewrite/avoid.xml	Thu May 14 19:17:27 2026	(r1934198)
@@ -106,6 +106,17 @@ the recommended configuration and the
 <module>mod_rewrite</module> alternative for <code>.htaccess</code>
 use.</p>
 
+    <note><title>Processing order</title>
+    <p>If you do mix <directive module="mod_alias">Redirect</directive>
+    and <directive module="mod_rewrite">RewriteRule</directive> in the
+    same context, be aware that their execution order depends on where
+    they appear. In server/virtual-host context,
+    <module>mod_rewrite</module> runs first; in per-directory context
+    (<code>.htaccess</code>), <module>mod_alias</module> runs first. See
+    <a href="tech.html#order">Module Processing Order</a> for
+    details.</p>
+    </note>
+
 </section>
 
 <section id="alias"><title>URL Aliasing</title>

Modified: httpd/httpd/trunk/docs/manual/rewrite/tech.xml
==============================================================================
--- httpd/httpd/trunk/docs/manual/rewrite/tech.xml	Thu May 14 17:09:54 2026	(r1934197)
+++ httpd/httpd/trunk/docs/manual/rewrite/tech.xml	Thu May 14 19:17:27 2026	(r1934198)
@@ -82,6 +82,53 @@ and URL matching.</p>
 
 </section>
 
+<section id="order"><title>Module Processing Order</title>
+
+    <p><module>mod_rewrite</module> and <module>mod_alias</module> both
+    operate during the URL-to-filename translation phase, but
+    <module>mod_rewrite</module> runs <strong>first</strong> regardless
+    of the order in which directives appear in the configuration file.
+    This is determined by the hook priority each module registers, not
+    by source order.</p>
+
+    <p>The practical consequence: when both <directive
+    module="mod_rewrite">RewriteRule</directive> and <directive
+    module="mod_alias">Redirect</directive> (or <directive
+    module="mod_alias">RedirectMatch</directive>) are present in the
+    same server or virtual-host context, the rewrite rules are
+    evaluated first. If a <code>RewriteRule</code> matches and rewrites
+    the URI (or returns a redirect), <code>Redirect</code> never sees
+    the request.</p>
+
+    <highlight language="config">
+# In this configuration, the Redirect is never reached for /old
+# because the RewriteRule matches first — even though
+# the Redirect appears earlier in the file.
+Redirect "/old" "http://example.com/new"
+RewriteRule "^/old" "/other" [L]
+</highlight>
+
+    <note><title>Per-directory context reverses the order</title>
+    <p>In <glossary ref="perdirectory">per-directory context</glossary>,
+    the situation is different. <module>mod_alias</module> directives like
+    <code>Redirect</code> still run in the URL-to-filename translation
+    phase, but <module>mod_rewrite</module> rules run later, in the
+    Fixup phase. This means that in per-directory context,
+    <code>Redirect</code> is evaluated <em>before</em>
+    <code>RewriteRule</code>.</p>
+    </note>
+
+    <p>Because of this inconsistency between contexts, mixing
+    <module>mod_rewrite</module> and <module>mod_alias</module>
+    directives in the same scope is a common source of confusion. The
+    simplest advice: choose one module for a given task. If you need
+    rewrite conditions or pattern matching, use
+    <code>RewriteRule</code> exclusively. If a simple prefix redirect
+    suffices, use <code>Redirect</code> and don't add rewrite rules
+    that might interact with it.</p>
+
+</section>
+
 <section id="InternalRuleset"><title>Ruleset Processing</title>
 
       <p>Now when <module>mod_rewrite</module> is triggered in these two API phases, it