reference/outcontrol/functions/output-add-rewrite-var.xml
b0d9505811e05bc11b58ef23167f3855c742edba
b0d9505811e05bc11b58ef23167f3855c742edba
...
...
@@ -14,25 +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>.
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.
22
24
</para>
23
25
<para>
24
-
This function's behaviour is controlled by the <link
25
-
linkend="ini.url-rewriter.tags">url_rewriter.tags</link> and
26
-
<link linkend="ini.url-rewriter.hosts">url_rewriter.hosts</link> &php.ini;
27
-
parameters.
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.
28
35
</para>
29
36
<para>
30
-
Note that this function can be successfully called at most once per request.
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.
31
41
</para>
32
42
<note>
33
43
<simpara>
34
-
Calling this function will implicitly start output buffering if it is
35
-
not active already.
44
+
Once the <literal>'URL-Rewriter'</literal> handler has been turned off
45
+
it cannot be started again.
36
46
</simpara>
37
47
</note>
38
48
</refsect1>
...
...
@@ -83,11 +93,13 @@
83
93
<row>
84
94
<entry>7.1.0</entry>
85
95
<entry>
86
-
Before PHP 7.1.0, rewrite vars set by <function>output_add_rewrite_var</function>
87
-
use the same Session module trans sid output buffer. Since PHP 7.1.0,
88
-
dedicated output buffer is used, <link linkend="ini.url-rewriter.tags">
89
-
url_rewriter.tags</link> is used solely for output functions, <link
90
-
linkend="ini.url-rewriter.tags">url_rewriter.hosts</link> is added.
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>).
91
103
</entry>
92
104
</row>
93
105
</tbody>
...
...
@@ -104,6 +116,8 @@
104
116
<programlisting role="php">
105
117
<![CDATA[
106
118
<?php
119
+
ini_set('url_rewriter.tags', 'a=href,form=');
120
+
107
121
output_add_rewrite_var('var', 'value');
108
122
109
123
// some links
...
...
@@ -149,8 +163,6 @@ Array
149
163
<member><function>ob_list_handlers</function></member>
150
164
<member><link linkend="ini.url-rewriter.tags">url_rewriter.tags</link></member>
151
165
<member><link linkend="ini.url-rewriter.hosts">url_rewriter.hosts</link></member>
152
-
<member><link linkend="ini.session.trans-sid-tags">session.trans_sid_tags</link></member>
153
-
<member><link linkend="ini.session.trans-sid-hosts">session.trans_sid_hosts</link></member>
154
166
</simplelist>
155
167
</para>
156
168
</refsect1>
157
169