php-doc-en/reference/strings/functions/setlocale.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.26 $ -->
<!-- splitted from ./en/functions/strings.xml, last change in rev 1.2 -->
  <refentry id="function.setlocale">
   <refnamediv>
    <refname>setlocale</refname>
    <refpurpose>Set locale information</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>setlocale</methodname>
      <methodparam><type>int</type><parameter>category</parameter></methodparam>
      <methodparam><type>string</type><parameter>locale</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>...</parameter></methodparam>
     </methodsynopsis>
     <methodsynopsis>
      <type>string</type><methodname>setlocale</methodname>
      <methodparam><type>int</type><parameter>category</parameter></methodparam>
      <methodparam><type>array</type><parameter>locale</parameter></methodparam>
     </methodsynopsis>
    <para>
     <parameter>category</parameter> is a named constant (or string)
     specifying the category of the functions affected by the locale
     setting:
     <itemizedlist>
      <listitem>
       <simpara>
        LC_ALL for all of the below
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        LC_COLLATE for string comparison, see
        <function>strcoll</function>
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        LC_CTYPE for character classification and conversion, for
        example <function>strtoupper</function>
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        LC_MONETARY for <function>localeconv</function>
       </simpara>
      </listitem>
      <listitem>
       <simpara> LC_NUMERIC for decimal separator (See also
       <function>localeconv</function>)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        LC_TIME for date and time formatting with
        <function>strftime</function>
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        LC_MESSAGES for system responses (available if PHP was compiled with
        <literal>libintl</literal>)
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <note>
     <simpara>
      As of PHP 4.2.0, passing <parameter>category</parameter> as a string is
      deprecated, use the above constants instead.  Passing them as a string
      (within quotes) will result in a warning message.
     </simpara>
    </note>
    <para>
     If <parameter>locale</parameter> is &null; or the empty string
     <literal>""</literal>, the locale names will be set from the
     values of environment variables with the same names as the above
     categories, or from "LANG".
    </para>
    <para>
     If <parameter>locale</parameter> is <literal>"0"</literal>,
     the locale setting is not affected, only the current setting is returned.
    </para>
    <para>
     If <parameter>locale</parameter> is an array or followed by additional
     parameters then each array element or parameter is tried to be set as
     new locale until success. This is useful if a locale is known under
     different names on different systems or for providing a fallback 
     for a possibly not available locale.
    </para>
    <note>
     <simpara>
      Passing multiple locales is not available before PHP 4.3.0
     </simpara>
    </note>
    <para>
     Setlocale returns the new current locale, or &false; if the locale
     functionality is not implemented on your platform, the specified
     locale does not exist or the category name is invalid.
     An invalid category name also causes a warning message. Category/locale
     names can be found in <ulink url="&url.rfc;1766">RFC 1766</ulink>
     and <ulink url="&url.iso-639;">ISO 639</ulink>.
     Different systems have different naming schemes for locales.
    </para>
    <note>
     <para>
      The return value of <function>setlocale</function> depends
      on the system that PHP is running.  It returns exactly
      what the system setlocale function returns.
     </para>
    </note>
    <warning>
     <para>
      The locale information is maintained per process, not per
      thread. If you are running PHP on a multithreaded server 
      api like IIS or Apache on Windows you may experience 
      sudden changes of locale settings while a script is 
      running although the script itself never called <function>setlocale</function>
      itself. This happens due to other scripts running in different
      threads of the same process at the same time changing the
      processwide locale using <function>setlocale</function>.
     </para>
    </warning>
    <tip>
     <para>
      Windows users will find useful information about
      <parameter>locale</parameter> strings at Microsoft's
      <acronym>MSDN</acronym>website. Supported language strings can be found
      at <ulink url="&url.setlocale.lang.win32;">&url.setlocale.lang.win32;</ulink> and supported
      country/region strings at <ulink url="&url.setlocale.country.win32;">
      &url.setlocale.country.win32;</ulink>. Windows systems support the three letter codes for
      country/region specified by <literal>ISO 3166-Alpha-3</literal>, which
      can be found at this <ulink url="&url.iso-3166-3;">Unicode website
      </ulink>. 
     </para>
    </tip>
    <para>
     <example>
      <title><function>setlocale</function> Examples</title>
      <programlisting role="php">
<![CDATA[
<?php
/* Set locale to Dutch */
setlocale(LC_ALL, 'nl_NL');

/* Output: vrijdag 22 december 1978 */
echo strftime("%A %e %B %Y", mktime(0, 0, 0, 12, 22, 1978));

/* try different possible locale names for german as of PHP 4.3.0 */
$loc_de = setlocale(LC_ALL, 'de_DE@euro', 'de_DE', 'de', 'ge');
echo "Preferred locale for german on this system is '$loc_de'";
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     <example>
      <title><function>setlocale</function> Examples for Windows</title>
      <programlisting role="php">
<![CDATA[
<?php
/* Set locale to Dutch */
setlocale(LC_ALL, 'nld_nld');

/* Output: vrijdag 22 december 1978 */
echo strftime("%A %d %B %Y", mktime(0, 0, 0, 12, 22, 1978));

/* try different possible locale names for german as of PHP 4.3.0 */
$loc_de = setlocale(LC_ALL, 'de_DE@euro', 'de_DE', 'deu_deu');
echo "Preferred locale for german on this system is '$loc_de'";
?>
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->