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 de761ba46e26e43c57e149eaa1903e28cc8a75f8..fef7930fac95d8ac1a9724073b6d488ab2463f91 100644 (file)
--- 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 06bd28adfb0ee7e390ba694df73e182a0c2b801d..fc2ee413d29772303995014cd208e1904cd12261 100644 (file)
--- 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 ae1c13e01ac59c4c180dae51c5b16dadda63eb3d..23c4e5aa50ab0e4648978cd8e59b17bab119af1a 100644 (file)
--- 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>