<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<section xml:id="mbstring.configuration" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 &reftitle.runtime;
 &extension.runtime;
 <para>
  <table>
   <title>mbstring configuration options</title>
   <tgroup cols="4">
    <thead>
     <row>
      <entry>&Name;</entry>
      <entry>&Default;</entry>
      <entry>&Changeable;</entry>
      <entry>&Changelog;</entry>
     </row>
    </thead>
    <tbody xml:id="mbstring.configuration.list">
     <row>
      <entry><link linkend="ini.mbstring.language">mbstring.language</link></entry>
      <entry>"neutral"</entry>
      <entry>PHP_INI_ALL</entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.mbstring.detect-order">mbstring.detect_order</link></entry>
      <entry>NULL</entry>
      <entry>PHP_INI_ALL</entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.mbstring.http-input">mbstring.http_input</link></entry>
      <entry>"pass"</entry>
      <entry>PHP_INI_ALL</entry>
      <entry>Deprecated</entry>
     </row>
     <row>
      <entry><link linkend="ini.mbstring.http-output">mbstring.http_output</link></entry>
      <entry>"pass"</entry>
      <entry>PHP_INI_ALL</entry>
      <entry>Deprecated</entry>
     </row>
     <row>
      <entry><link linkend="ini.mbstring.internal-encoding">mbstring.internal_encoding</link></entry>
      <entry>NULL</entry>
      <entry>PHP_INI_ALL</entry>
      <entry>Deprecated</entry>
     </row>
     <row>
      <entry><link linkend="ini.mbstring.substitute-character">mbstring.substitute_character</link></entry>
      <entry>NULL</entry>
      <entry>PHP_INI_ALL</entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.mbstring.func-overload">mbstring.func_overload</link></entry>
      <entry>"0"</entry>
      <entry>PHP_INI_SYSTEM</entry>
      <entry>
       Deprecated as of PHP 7.2.0; removed as of PHP 8.0.0.
      </entry>
     </row>
     <row>
      <entry><link linkend="ini.mbstring.encoding-translation">mbstring.encoding_translation</link></entry>
      <entry>"0"</entry>
      <entry>PHP_INI_PERDIR</entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.mbstring.http-output-conv-mimetypes">mbstring.http_output_conv_mimetypes</link></entry>
      <entry>"^(text/|application/xhtml\+xml)"</entry>
      <entry>PHP_INI_ALL</entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.mbstring.strict-detection">mbstring.strict_detection</link></entry>
      <entry>"0"</entry>
      <entry>PHP_INI_ALL</entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.mbstring.regex-retry-limit">mbstring.regex_retry_limit</link></entry>
      <entry>"1000000"</entry>
      <entry>PHP_INI_ALL</entry>
      <entry>Available as of PHP 7.4.0.</entry>
     </row>
     <row>
      <entry><link linkend="ini.mbstring.regex-stack-limit">mbstring.regex_stack_limit</link></entry>
      <entry>"100000"</entry>
      <entry>PHP_INI_ALL</entry>
      <entry>Available as of PHP 7.3.5.</entry>
     </row>
    </tbody>
   </tgroup>
  </table>
  &ini.php.constants;
 </para>
 
 &ini.descriptions.title;
 
 <para>
  <variablelist>
   <varlistentry xml:id="ini.mbstring.language">
    <term>
     <parameter>mbstring.language</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
      The default national language setting (NLS) used in mbstring. Note that this option
      automagically defines <literal>mbstring.internal_encoding</literal> and
      <literal>mbstring.internal_encoding</literal> should be placed
      after <literal>mbstring.language</literal> in &php.ini;
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mbstring.encoding-translation">
    <term>
     <parameter>mbstring.encoding_translation</parameter>
     <type>bool</type>
    </term>
    <listitem>
     <para>
      Enables the transparent character encoding filter for the incoming HTTP queries,
      which performs detection and conversion of the input encoding to the
      internal character encoding. 
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mbstring.internal-encoding">
    <term>
     <parameter>mbstring.internal_encoding</parameter>
     <type>string</type>
    </term>
    <listitem>
     <warning>
      <para>&removed.php.future;</para>
     </warning>
     <para>
      Defines the default internal character encoding.
     </para>
     <para>
      Users should leave this empty and set
      <link linkend="ini.default-charset"><parameter>default_charset</parameter></link>
      instead.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mbstring.http-input">
    <term>
     <parameter>mbstring.http_input</parameter>
     <type>string</type>
    </term>
    <listitem>
     <warning>
      <para>&removed.php.future;</para>
     </warning>
     <para>
      Defines the default HTTP input character encoding.
     </para>
     <para>
      Users should leave this empty and set
      <link linkend="ini.default-charset"><parameter>default_charset</parameter></link>
      instead.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mbstring.http-output">
    <term>
     <parameter>mbstring.http_output</parameter>
     <type>string</type>
    </term>
    <listitem>
     <warning>
      <para>&removed.php.future;</para>
     </warning>
     <para>
      Defines the default HTTP output character encoding (output will be converted from the internal encoding to the HTTP output encoding upon output).
     </para>
     <para>
      Users should leave this empty and set
      <link linkend="ini.default-charset"><parameter>default_charset</parameter></link>
      instead.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mbstring.detect-order">
    <term>
     <parameter>mbstring.detect_order</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
      Defines default character code detection order. See also
      <function>mb_detect_order</function>. 
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mbstring.substitute-character">
    <term>
     <parameter>mbstring.substitute_character</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
      Defines character to substitute for invalid character encoding.
      See <function>mb_substitute_character</function> for supported values.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mbstring.func-overload">
    <term>
     <parameter>mbstring.func_overload</parameter>
     <type>string</type>
    </term>
    <listitem>
     &warn.deprecated.feature-7-2-0.removed-8-0-0;
     <para>
      Overloads a set of single byte functions by the mbstring counterparts. See
      <link linkend="mbstring.overload">Function overloading</link> for more
      information.
     </para>
     <para>
      This setting can only be changed from the &php.ini; file.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mbstring.http-output-conv-mimetypes">
    <term>
     <parameter>mbstring.http_output_conv_mimetypes</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mbstring.strict-detection">
    <term>
     <parameter>mbstring.strict_detection</parameter>
     <type>bool</type>
    </term>
    <listitem>
     <para>
      Enables strict encoding detection. See <function>mb_detect_encoding</function>
      for a description and examples.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mbstring.regex-retry-limit">
    <term>
     <parameter>mbstring.regex_retry_limit</parameter>
     <type>int</type>
    </term>
    <listitem>
     <para>
      Limits the amount of backtracking that may be performed during one mbregex
      match.
     </para>
     <para>
      This setting only takes effect when linking against oniguruma >= 6.8.0.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mbstring.regex-stack-limit">
    <term>
     <parameter>mbstring.regex_stack_limit</parameter>
     <type>int</type>
    </term>
    <listitem>
     <para>
      Limits the stack depth of mbstring regular expressions.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </para>

 <para>
  According to the <link xlink:href="&url.spec.html401.accept-charset;">HTML 4.01 specification</link>,
  Web browsers are allowed to encode a form being submitted with a character
  encoding different from the one used for the page.
  See <function>mb_http_input</function> to detect character encoding
  used by browsers.
 </para>
 <para>
  Although popular browsers are capable of giving a reasonably accurate guess
  to the character encoding of a given HTML document, it would be better to
  set the <literal>charset</literal> parameter in the
  <literal>Content-Type</literal> HTTP header to the appropriate value by
  <function>header</function> or
  <link linkend="ini.sect.data-handling">default_charset</link> ini setting.
 </para>
 <para>
  <example>
  <title>&php.ini; setting examples</title>
   <programlisting>
<![CDATA[
; Set default language
mbstring.language        = Neutral; Set default language to Neutral(UTF-8) (default)
mbstring.language        = English; Set default language to English 
mbstring.language        = Japanese; Set default language to Japanese

;; Set default internal encoding
;; Note: Make sure to use character encoding works with PHP
mbstring.internal_encoding    = UTF-8  ; Set internal encoding to UTF-8

;; HTTP input encoding translation is enabled.
mbstring.encoding_translation = On

;; Set default HTTP input character encoding
;; Note: Script cannot change http_input setting.
mbstring.http_input           = pass    ; No conversion. 
mbstring.http_input           = auto    ; Set HTTP input to auto
                                ; "auto" is expanded according to mbstring.language
mbstring.http_input           = SJIS    ; Set HTTP input to SJIS
mbstring.http_input           = UTF-8,SJIS,EUC-JP ; Specify order

;; Set default HTTP output character encoding 
mbstring.http_output          = pass    ; No conversion
mbstring.http_output          = UTF-8   ; Set HTTP output encoding to UTF-8

;; Set default character encoding detection order
mbstring.detect_order         = auto    ; Set detect order to auto
mbstring.detect_order         = ASCII,JIS,UTF-8,SJIS,EUC-JP ; Specify order

;; Set default substitute character
mbstring.substitute_character = 12307   ; Specify Unicode value
mbstring.substitute_character = none    ; Do not print character
mbstring.substitute_character = long    ; Long Example: U+3000,JIS+7E7E
]]>
   </programlisting>
  </example>
 </para>
 <para>
  <example>
   <title>&php.ini; setting for <literal>EUC-JP</literal> users</title>
   <programlisting>
<![CDATA[
;; Disable Output Buffering
output_buffering      = Off

;; Set HTTP header charset
default_charset       = EUC-JP    

;; Set default language to Japanese
mbstring.language = Japanese

;; HTTP input encoding translation is enabled.
mbstring.encoding_translation = On

;; Set HTTP input encoding conversion to auto
mbstring.http_input   = auto 

;; Convert HTTP output to EUC-JP
mbstring.http_output  = EUC-JP    

;; Set internal encoding to EUC-JP
mbstring.internal_encoding = EUC-JP    

;; Do not print invalid characters
mbstring.substitute_character = none   
]]>
   </programlisting>
  </example>
 </para>
 <para>
  <example>
   <title>&php.ini; setting for <literal>SJIS</literal> users</title>
   <programlisting>
<![CDATA[
;; Enable Output Buffering
output_buffering     = On

;; Set mb_output_handler to enable output conversion
output_handler       = mb_output_handler

;; Set HTTP header charset
default_charset      = Shift_JIS

;; Set default language to Japanese
mbstring.language = Japanese

;; Set http input encoding conversion to auto
mbstring.http_input  = auto 

;; Convert to SJIS
mbstring.http_output = SJIS    

;; Set internal encoding to EUC-JP
mbstring.internal_encoding = EUC-JP    

;; Do not print invalid characters
mbstring.substitute_character = none   
]]>
   </programlisting>
  </example>
 </para>

</section>

<!-- 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:"~/.phpdoc/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
-->
