reference/strings/functions/setlocale.xml
09324fb1df7b5b1c0a5f95e3ebbe802f59da4585
09324fb1df7b5b1c0a5f95e3ebbe802f59da4585
...
...
@@ -9,19 +9,32 @@
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
-
<type>string</type><methodname>setlocale</methodname>
12
+
<type class="union"><type>string</type><type>false</type></type><methodname>setlocale</methodname>
13
13
<methodparam><type>int</type><parameter>category</parameter></methodparam>
14
-
<methodparam><type>string</type><parameter>locale</parameter></methodparam>
15
-
<methodparam choice="opt"><type>string</type><parameter>...</parameter></methodparam>
14
+
<methodparam><type class="union"><type>string</type><type>null</type></type><parameter>locales</parameter></methodparam>
15
+
<methodparam rep="repeat"><type>string</type><parameter>rest</parameter></methodparam>
16
16
</methodsynopsis>
17
+
<simpara>Alternative signature (not supported with named arguments):</simpara>
17
18
<methodsynopsis>
18
-
<type>string</type><methodname>setlocale</methodname>
19
+
<type class="union"><type>string</type><type>false</type></type><methodname>setlocale</methodname>
19
20
<methodparam><type>int</type><parameter>category</parameter></methodparam>
20
-
<methodparam><type>array</type><parameter>locale</parameter></methodparam>
21
+
<methodparam><type>array</type><parameter>locale_array</parameter></methodparam>
21
22
</methodsynopsis>
22
23
<para>
23
24
Sets locale information.
24
25
</para>
26
+
<warning>
27
+
<para>
28
+
The locale information is maintained per process, not per thread. If you
29
+
are running PHP on a multithreaded server API
30
+
, you may experience sudden changes in locale settings while a
31
+
script is running, though the script itself never called
32
+
<function>setlocale</function>. This happens due to other scripts
33
+
running in different threads of the same process at the same time,
34
+
changing the process-wide locale using <function>setlocale</function>.
35
+
On Windows, locale information is maintained per thread as of PHP 7.0.5.
36
+
</para>
37
+
</warning>
25
38
</refsect1>
26
39
27
40
<refsect1 role="parameters">
...
...
@@ -49,7 +62,7 @@
49
62
<listitem>
50
63
<simpara>
51
64
<constant>LC_CTYPE</constant> for character classification and conversion, for
52
-
example <function>strtoupper</function>
65
+
example <function>ctype_alpha</function>
53
66
</simpara>
54
67
</listitem>
55
68
<listitem>
...
...
@@ -80,21 +93,21 @@
80
93
</listitem>
81
94
</varlistentry>
82
95
<varlistentry>
83
-
<term><parameter>locale</parameter></term>
96
+
<term><parameter>locales</parameter></term>
84
97
<listitem>
85
98
<para>
86
-
If <parameter>locale</parameter> is &null; or the empty string
87
-
<literal>""</literal>, the locale names will be set from the
99
+
If <parameter>locales</parameter> is the empty string
100
+
<literal>""</literal> or is &null;, the locale names will be set from the
88
101
values of environment variables with the same names as the above
89
102
categories, or from "LANG".
90
103
</para>
91
104
<para>
92
-
If <parameter>locale</parameter> is <literal>"0"</literal>,
105
+
If <parameter>locales</parameter> is <literal>"0"</literal>,
93
106
the locale setting is not affected, only the current setting is returned.
94
107
</para>
95
108
<para>
96
-
If <parameter>locale</parameter> is an array or followed by additional
97
-
parameters then each array element or parameter is tried to be set as
109
+
If <parameter>locales</parameter> is followed by additional
110
+
parameters then each parameter is tried to be set as
98
111
new locale until success. This is useful if a locale is known under
99
112
different names on different systems or for providing a fallback
100
113
for a possibly not available locale.
...
...
@@ -102,11 +115,22 @@
102
115
</listitem>
103
116
</varlistentry>
104
117
<varlistentry>
105
-
<term><parameter>...</parameter></term>
118
+
<term><parameter>rest</parameter></term>
106
119
<listitem>
107
120
<para>
108
-
(Optional string or array parameters to try as locale settings until
109
-
success.)
121
+
Optional string parameters to try as locale settings until
122
+
success.
123
+
</para>
124
+
</listitem>
125
+
</varlistentry>
126
+
<varlistentry>
127
+
<term><parameter>locale_array</parameter></term>
128
+
<listitem>
129
+
<para>
130
+
Each array element is tried to be set as
131
+
new locale until success. This is useful if a locale is known under
132
+
different names on different systems or for providing a fallback
133
+
for a possibly not available locale.
110
134
</para>
111
135
</listitem>
112
136
</varlistentry>
...
...
@@ -142,45 +166,12 @@
142
166
</note>
143
167
</refsect1>
144
168
145
-
<refsect1 role="changelog">
146
-
&reftitle.changelog;
147
-
<para>
148
-
<informaltable>
149
-
<tgroup cols="2">
150
-
<thead>
151
-
<row>
152
-
<entry>&Version;</entry>
153
-
<entry>&Description;</entry>
154
-
</row>
155
-
</thead>
156
-
<tbody>
157
-
<row>
158
-
<entry>7.0.0</entry>
159
-
<entry>
160
-
Support for the <parameter>category</parameter> parameter passed as a string has
161
-
been removed. Only <literal>LC_*</literal> constants can be used as of this version.
162
-
</entry>
163
-
</row>
164
-
<row>
165
-
<entry>5.3.0</entry>
166
-
<entry>
167
-
This function now throws an <constant>E_DEPRECATED</constant> notice if a string is passed
168
-
to the <parameter>category</parameter> parameter instead of one of the
169
-
<literal>LC_*</literal> constants.
170
-
</entry>
171
-
</row>
172
-
</tbody>
173
-
</tgroup>
174
-
</informaltable>
175
-
</para>
176
-
</refsect1>
177
-
178
169
<refsect1 role="examples">
179
170
&reftitle.examples;
180
171
<para>
181
172
<example>
182
173
<title><function>setlocale</function> Examples</title>
183
-
<programlisting role="php">
174
+
<programlisting role="php" annotations="non-interactive">
184
175
<![CDATA[
185
176
<?php
186
177
/* Set locale to Dutch */
...
...
@@ -193,6 +184,21 @@ echo strftime("%A %e %B %Y", mktime(0, 0, 0, 12, 22, 1978));
193
184
$loc_de = setlocale(LC_ALL, 'de_DE@euro', 'de_DE', 'de', 'ge');
194
185
echo "Preferred locale for german on this system is '$loc_de'";
195
186
?>
187
+
]]>
188
+
</programlisting>
189
+
</example>
190
+
</para>
191
+
<para>
192
+
<example>
193
+
<title><function>setlocale</function> Retrieve current setting</title>
194
+
<programlisting role="php" annotations="non-interactive">
195
+
<![CDATA[
196
+
<?php
197
+
/* Retrieve current setting */
198
+
$current = setlocale(LC_ALL, null);
199
+
200
+
echo "Current locale '$current'";
201
+
?>
196
202
]]>
197
203
</programlisting>
198
204
</example>
...
...
@@ -200,7 +206,7 @@ echo "Preferred locale for german on this system is '$loc_de'";
200
206
<para>
201
207
<example>
202
208
<title><function>setlocale</function> Examples for Windows</title>
203
-
<programlisting role="php">
209
+
<programlisting role="php" annotations="non-interactive">
204
210
<![CDATA[
205
211
<?php
206
212
/* Set locale to Dutch */
...
...
@@ -221,21 +227,10 @@ echo "Preferred locale for german on this system is '$loc_de'";
221
227
222
228
<refsect1 role="notes">
223
229
&reftitle.notes;
224
-
<warning>
225
-
<para>
226
-
The locale information is maintained per process, not per thread. If you
227
-
are running PHP on a multithreaded server API like IIS, HHVM or Apache on
228
-
Windows, you may experience sudden changes in locale settings while a
229
-
script is running, though the script itself never called
230
-
<function>setlocale</function>. This happens due to other scripts
231
-
running in different threads of the same process at the same time,
232
-
changing the process-wide locale using <function>setlocale</function>.
233
-
</para>
234
-
</warning>
235
230
<tip>
236
231
<para>
237
232
Windows users will find useful information about
238
-
<parameter>locale</parameter> strings at Microsoft's
233
+
<parameter>locales</parameter> strings at Microsoft's
239
234
<acronym>MSDN</acronym> website. Supported language strings can be found
240
235
in the
241
236
<link xlink:href="&url.setlocale.lang.win32;">language strings documentation</link>
...
...
@@ -246,7 +241,6 @@ echo "Preferred locale for german on this system is '$loc_de'";
246
241
</refsect1>
247
242
248
243
</refentry>
249
-
250
244
<!-- Keep this comment at the end of the file
251
245
Local variables:
252
246
mode: sgml
253
247