From: Rich Bowen <rbowen@apache.org>
Date: Thu, 14 May 2026 20:30:43 +0000 (+0000)
Subject: rewrite guide: document REDIRECT_ prefix for [E=] environment variables
X-Git-Url: http://git.ipfire.org/gitweb/index.cgi?a=commitdiff_plain;h=c24819471003f808cd189d18fb15e77b7a9e9cfd;p=thirdparty%2Fapache%2Fhttpd.git

rewrite guide: document REDIRECT_ prefix for [E=] environment variables

flags.xml: expand the [E] flag section with a note box explaining
that per-directory rewrites rename env vars with a REDIRECT_ prefix
after internal redirect, with an example showing how to reference the
renamed variable and a note about prefix stacking.

env.xml: add cross-reference from the REDIRECT_ variables section
back to rewrite/flags.html#flag_e for mod_rewrite-specific details.


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1934203 13f79535-47bb-0310-9956-ffa450edef68
---

diff --git a/docs/manual/env.xml b/docs/manual/env.xml
index de761ba46e..fef7930fac 100644
--- a/docs/manual/env.xml
+++ b/docs/manual/env.xml
@@ -537,6 +537,12 @@
     about REDIRECT_ variables in the context of error documents,
     see <a href="custom-error.html">Custom Error Responses</a>.</p>
 
+    <p>This renaming is especially relevant when using
+    <module>mod_rewrite</module>'s
+    <a href="rewrite/flags.html#flag_e">[E] flag</a> to set variables,
+    since per-directory rewrites always trigger an internal redirect.
+    See that section for examples and workarounds.</p>
+
    </section>
 
   <section id="examples">
diff --git a/docs/manual/rewrite/TODO.md b/docs/manual/rewrite/TODO.md
index 06bd28adfb..fc2ee413d2 100644
--- a/docs/manual/rewrite/TODO.md
+++ b/docs/manual/rewrite/TODO.md
@@ -72,7 +72,7 @@ address. Sorted by priority.
       explanation exists in the guide. Could be a new section in
       intro.xml or tech.xml.
 
-- [ ] **REDIRECT_ prefix for environment variables** — env vars set by
+- [x] **REDIRECT_ prefix for environment variables** — env vars set by
       [E=] are renamed to REDIRECT_FOO after internal redirects. Not
       mentioned in the [E] flag section at all. Add to flags.xml.
 
diff --git a/docs/manual/rewrite/flags.xml b/docs/manual/rewrite/flags.xml
index ae1c13e01a..23c4e5aa50 100644
--- a/docs/manual/rewrite/flags.xml
+++ b/docs/manual/rewrite/flags.xml
@@ -376,10 +376,34 @@ RewriteCond "%{ENV:rewritten}"  =1
 
 <p>Note that environment variables do not survive an external
 redirect. You might consider using the [CO] flag to set a
-cookie. For per-directory rewrites, where the final
-substitution is processed as an internal redirect, environment
-variables from the previous round of rewriting are prefixed with
-"REDIRECT_". </p>
+cookie.</p>
+
+    <note><title>REDIRECT_ prefix after internal redirects</title>
+    <p>In <glossary ref="perdirectory">per-directory context</glossary>,
+    a successful substitution triggers an internal redirect. When this
+    happens, all environment variables set during the previous pass —
+    including those created with <code>[E=VAR:VAL]</code> — are renamed
+    with a <code>REDIRECT_</code> prefix. A variable you set as
+    <code>rewritten</code> becomes <code>REDIRECT_rewritten</code> in
+    the redirected request.</p>
+
+    <p>To test for the renamed variable, reference it with the
+    prefix:</p>
+    </note>
+
+<highlight language="config">
+RewriteRule   "^/horses/(.*)" "/ponies/$1" [E=rewritten:1]
+
+# In the next pass, the variable has been renamed:
+RewriteCond "%{ENV:REDIRECT_rewritten}" =1
+RewriteRule "^/ponies/(.*)" "-" [E=seen_redirect:1,L]
+</highlight>
+
+    <p>If the request is redirected multiple times, the prefix stacks:
+    <code>REDIRECT_REDIRECT_rewritten</code>, and so on. See
+    <a href="../env.html#redirect-vars">REDIRECT_ variables</a> for
+    the complete description of this mechanism.</p>
+
 </section>
 
 <section id="flag_end"><title>END</title>