reference/outcontrol/functions/output-add-rewrite-var.xml
b0d9505811e05bc11b58ef23167f3855c742edba
b0d9505811e05bc11b58ef23167f3855c742edba
...
...
@@ -14,22 +14,35 @@
14
14
<methodparam><type>string</type><parameter>value</parameter></methodparam>
15
15
</methodsynopsis>
16
16
<para>
17
-
This function adds another name/value pair to the URL rewrite mechanism.
18
-
The name and value will be added to URLs (as GET parameter) and forms
19
-
(as hidden input fields) the same way as the session ID when transparent
20
-
URL rewriting is enabled with <link
21
-
linkend="ini.session.use-trans-sid">session.use_trans_sid</link>. Please
22
-
note that absolute URLs (http://example.com/..) aren't rewritten.
17
+
This function starts the <literal>'URL-Rewriter'</literal> output buffer handler
18
+
if it is not active,
19
+
stores the <parameter>name</parameter> and <parameter>value</parameter> parameters,
20
+
and when the buffer is flushed rewrites the <acronym>URL</acronym>s
21
+
and forms based on the applicable ini settings.
22
+
Subsequent calls to this function will store all additional name/value pairs
23
+
until the handler is turned off.
23
24
</para>
24
25
<para>
25
-
This function's behavior is controlled by the <link
26
-
linkend="ini.url-rewriter.tags">url_rewriter.tags</link> &php.ini;
27
-
parameter.
26
+
When the output buffer is flushed
27
+
(by calling <function>ob_flush</function>, <function>ob_end_flush</function>,
28
+
<function>ob_get_flush</function> or at the end of the script)
29
+
the <literal>'URL-Rewriter'</literal> handler adds the name/value pairs
30
+
as query parameters to <acronym>URL</acronym>s in attributes of HTML tags
31
+
and adds hidden fields to forms based on the values of the
32
+
<link linkend="ini.url-rewriter.tags">url_rewriter.tags</link> and
33
+
<link linkend="ini.url-rewriter.hosts">url_rewriter.hosts</link>
34
+
configuration directives.
35
+
</para>
36
+
<para>
37
+
Each name/value pair added to the <literal>'URL-Rewriter'</literal> handler
38
+
is added to the <acronym>URL</acronym>s and/or forms
39
+
even if this results in duplicate <acronym>URL</acronym> query parameters
40
+
or elements with the same name attributes.
28
41
</para>
29
42
<note>
30
43
<simpara>
31
-
Calling this function will implicitly start output buffering if it is
32
-
not active already.
44
+
Once the <literal>'URL-Rewriter'</literal> handler has been turned off
45
+
it cannot be started again.
33
46
</simpara>
34
47
</note>
35
48
</refsect1>
...
...
@@ -65,6 +78,36 @@
65
78
</para>
66
79
</refsect1>
67
80
81
+
<refsect1 role="changelog">
82
+
&reftitle.changelog;
83
+
<para>
84
+
<informaltable>
85
+
<tgroup cols="2">
86
+
<thead>
87
+
<row>
88
+
<entry>&Version;</entry>
89
+
<entry>&Description;</entry>
90
+
</row>
91
+
</thead>
92
+
<tbody>
93
+
<row>
94
+
<entry>7.1.0</entry>
95
+
<entry>
96
+
As of PHP 7.1.0, a dedicated output buffer is used,
97
+
<link linkend="ini.url-rewriter.tags">url_rewriter.tags</link>
98
+
is used solely for output functions and
99
+
<link linkend="ini.url-rewriter.tags">url_rewriter.hosts</link> is available.
100
+
Prior to PHP 7.1.0, rewrite variables set by <function>output_add_rewrite_var</function>
101
+
shared an output buffer with transparent session id support
102
+
(see <link linkend="ini.session.trans-sid-tags">session.trans_sid_tags</link>).
103
+
</entry>
104
+
</row>
105
+
</tbody>
106
+
</tgroup>
107
+
</informaltable>
108
+
</para>
109
+
</refsect1>
110
+
68
111
<refsect1 role="examples">
69
112
&reftitle.examples;
70
113
<para>
...
...
@@ -73,6 +116,8 @@
73
116
<programlisting role="php">
74
117
<![CDATA[
75
118
<?php
119
+
ini_set('url_rewriter.tags', 'a=href,form=');
120
+
76
121
output_add_rewrite_var('var', 'value');
77
122
78
123
// some links
...
...
@@ -116,6 +161,8 @@ Array
116
161
<member><function>output_reset_rewrite_vars</function></member>
117
162
<member><function>ob_flush</function></member>
118
163
<member><function>ob_list_handlers</function></member>
164
+
<member><link linkend="ini.url-rewriter.tags">url_rewriter.tags</link></member>
165
+
<member><link linkend="ini.url-rewriter.hosts">url_rewriter.hosts</link></member>
119
166
</simplelist>
120
167
</para>
121
168
</refsect1>
122
169