From: Rich Bowen <rbowen@apache.org>
Date: Wed, 20 May 2026 20:52:39 +0000 (+0000)
Subject: rewrite: warn that <If>/<Location>/<Directory> silently switch to per-directory context
X-Git-Tag: 2.4.68-rc1-candidate~106
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=b9dd7c117fc31b35b3282660bd3088153839bed0;p=thirdparty%2Fapache%2Fhttpd.git

rewrite: warn that <If>/<Location>/<Directory> silently switch to per-directory context

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1934452 13f79535-47bb-0310-9956-ffa450edef68
---

diff --git a/docs/manual/rewrite/htaccess.xml b/docs/manual/rewrite/htaccess.xml
index 6d5d0b61c2..a11ff66739 100644
--- a/docs/manual/rewrite/htaccess.xml
+++ b/docs/manual/rewrite/htaccess.xml
@@ -340,4 +340,39 @@ performance.</note>
 
 </section>
 
+<section id="context-restrictions"><title>Which contexts support rewrite rules?</title>
+
+<p>Rewrite rules are supported in
+<glossary ref="perdirectory">per-directory context</glossary>
+(<a href="../howto/htaccess.html">.htaccess</a> files,
+<directive module="core" type="section">Directory</directive>, and
+<directive module="core" type="section">If</directive> blocks).</p>
+
+<p>Although rewrite rules are syntactically permitted in
+<directive module="core" type="section">Location</directive>
+and <directive module="core" type="section">Files</directive>
+sections (including their regex counterparts), this is
+unsupported and should never be necessary. Relative
+substitutions, in particular, are likely to break in
+these contexts.</p>
+
+<note type="warning"><title>These containers silently change rewrite
+behavior</title>
+<p>Placing a <directive module="mod_rewrite">RewriteRule</directive>
+inside a <directive module="core" type="section">Directory</directive>,
+<directive module="core" type="section">If</directive>, or
+<directive module="core" type="section">Location</directive> block
+&mdash; even inside a
+<directive module="core" type="section">VirtualHost</directive> in the
+main server config &mdash; silently switches to
+<glossary ref="perdirectory">per-directory context</glossary> behavior.
+This means the leading slash is stripped from the URL before pattern
+matching, substitutions trigger an internal redirect (with loop risk),
+and the <a href="../rewrite/flags.html#flag_l">[L]</a> flag no longer
+truly stops processing &mdash; use
+<a href="../rewrite/flags.html#flag_end">[END]</a> instead.</p>
+</note>
+
+</section>
+
 </manualpage>
diff --git a/docs/manual/rewrite/intro.xml b/docs/manual/rewrite/intro.xml
index 95b98c9623..eceb468fe3 100644
--- a/docs/manual/rewrite/intro.xml
+++ b/docs/manual/rewrite/intro.xml
@@ -391,7 +391,12 @@ recommended. It is possible, however, to do rewriting
 inside <directive type="section" module="core">Directory</directive>
 sections or <a href="../howto/htaccess.html"><code>.htaccess</code>
 files</a> at the expense of some additional complexity. This technique
-is called <glossary ref="perdirectory">per-directory</glossary> rewrites.</p>
+is called <glossary ref="perdirectory">per-directory</glossary> rewrites.
+Note that
+<directive module="core" type="section">If</directive> and
+<directive module="core" type="section">Location</directive> blocks
+also trigger per-directory behavior &mdash; see
+<a href="htaccess.html#context-restrictions">Which contexts support rewrite rules?</a>.</p>
 
 <p>The main difference from per-server rewrites is that the path
 prefix of the directory containing the <code>.htaccess</code> file is