<HTML
><HEAD
><TITLE
>Multi-Byte String Functions</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
TITLE="PHP Manual"
HREF="index.html"><LINK
REL="UP"
TITLE="Function Reference"
HREF="funcref.html"><LINK
REL="PREVIOUS"
TITLE="tanh"
HREF="function.tanh.html"><LINK
REL="NEXT"
TITLE="mb_convert_case"
HREF="function.mb-convert-case.html"><META
HTTP-EQUIV="Content-type"
CONTENT="text/html; charset=ISO-8859-1"></HEAD
><BODY
CLASS="reference"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>PHP Manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="function.tanh.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="function.mb-convert-case.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="reference"
><A
NAME="ref.mbstring"
></A
><DIV
CLASS="TITLEPAGE"
><H1
CLASS="title"
>LII. Multi-Byte String Functions</H1
><DIV
CLASS="PARTINTRO"
><A
NAME="AEN45359"
></A
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="mbstring.intro"
></A
>Introduction</H1
><P
> There are many languages in which all characters can be expressed
by single byte. Multi-byte character codes are used to express
many characters for many languages. <TT
CLASS="literal"
>mbstring</TT
>
is developed to handle Japanese characters. However, many
<TT
CLASS="literal"
>mbstring</TT
> functions are able to handle
character encoding other than Japanese.
</P
><P
> A multi-byte character encoding represents single character with
consecutive bytes. Some character encoding has shift(escape)
sequences to start/end multi-byte character strings. Therefore, a
multi-byte character string may be destroyed when it is divided
and/or counted unless multi-byte character encoding safe method
is used. This module provides multi-byte character safe string
functions and other utility functions such as conversion
functions.
</P
><P
> Since PHP is basically designed for ISO-8859-1, some multi-byte
character encoding does not work well with PHP. Therefore, it is
important to set <TT
CLASS="literal"
>mbstring.internal_encoding</TT
> to
a character encoding that works with PHP.
</P
><P
> PHP4 Character Encoding Requirements
</P
><P
> <P
></P
><UL
><LI
><P
> Per byte encoding
</P
></LI
><LI
><P
> Single byte characters in range of <TT
CLASS="literal"
>00h-7fh</TT
>
which is compatible with <TT
CLASS="literal"
>ASCII</TT
>
</P
></LI
><LI
><P
> Multi-byte characters without <TT
CLASS="literal"
>00h-7fh</TT
>
</P
></LI
></UL
>
</P
><P
> These are examples of internal character encoding that works with
PHP and does NOT work with PHP.
<DIV
CLASS="informalexample"
><A
NAME="AEN45381"
></A
><P
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>Character encodings work with PHP:
ISO-8859-*, EUC-JP, UTF-8
Character encodings do NOT work with PHP:
JIS, SJIS</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
>
</P
><P
> Character encoding, that does not work with PHP, may be converted
with <TT
CLASS="literal"
>mbstring</TT
>'s HTTP input/output conversion
feature/function.
</P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>
SJIS should not be used for internal encoding unless the reader
is familiar with parser/compiler, character encoding and
character encoding issues.
</P
></BLOCKQUOTE
></DIV
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>
If you use databases with PHP, it is recommended that you use the
same character encoding for both database and <TT
CLASS="literal"
>internal
encoding</TT
> for ease of use and better performance.
</P
><P
> If you are using PostgreSQL, it supports character
encoding that is different from backend character encoding. See
the PostgreSQL manual for details.
</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="mbstring.installation"
></A
>Installation</H1
><P
> <TT
CLASS="literal"
>mbstring</TT
> is an extended module. You must
enable the module with the <TT
CLASS="literal"
>configure</TT
> script.
Refer to the <A
HREF="installation.html"
>Install</A
> section for
details.
</P
><P
> The following configure options are related to the
<TT
CLASS="literal"
>mbstring</TT
> module.
</P
><P
> <P
></P
><UL
><LI
><P
> <TT
CLASS="option"
>--enable-mbstring</TT
>: Enable
<TT
CLASS="literal"
>mbstring</TT
> functions. This option is
required to use <TT
CLASS="literal"
>mbstring</TT
> functions.
</P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>
As of PHP 4.3.0, the option
<TT
CLASS="option"
>--enable-mbstring</TT
>
will be enabled by default and replaced with
<TT
CLASS="option"
>--with-mbstring[=LANG]</TT
>
to support Chinese, Korean and Russian language support.
Japanese character encoding is supported by default.
If <TT
CLASS="option"
>--with-mbstring=cn</TT
>
is used, simplified chinese encoding will be supported.
If <TT
CLASS="option"
>--with-mbstring=tw</TT
>
is used, traditional chinese encoding will be supported.
If <TT
CLASS="option"
>--with-mbstring=kr</TT
>
is used, korean encoding will be supported.
If <TT
CLASS="option"
>--with-mbstring=ru</TT
>
is used, russian encoding will be supported.
If <TT
CLASS="option"
>--with-mbstring=all</TT
>
is added, all supported character encoding in mbstring
will be enabled, but the binary size of PHP will be
maximized because of huge Unicode character maps.
Note that Chinese, Korean and Russian encoding is
experimentally supported in PHP 4.3.0.
</P
></BLOCKQUOTE
></DIV
></LI
><LI
><P
> <TT
CLASS="option"
>--enable-mbstr-enc-trans</TT
> :
Enable HTTP input character encoding conversion using
<TT
CLASS="literal"
>mbstring</TT
> conversion engine. If this
feature is enabled, HTTP input character encoding may be
converted to <TT
CLASS="literal"
>mbstring.internal_encoding</TT
>
automatically.
</P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>
As of PHP 4.3.0, the option
<TT
CLASS="option"
>--enable-mbstr-enc-trans</TT
>
will be eliminated and replaced with
<TT
CLASS="literal"
>mbstring.encoding_translation</TT
>.
HTTP input character encoding conversion is enabled
when this is set to <TT
CLASS="literal"
>On</TT
>
(the default is <TT
CLASS="literal"
>Off</TT
>).
</P
></BLOCKQUOTE
></DIV
></LI
><LI
><P
> <TT
CLASS="option"
>--enable-mbregex</TT
>: Enable
regular expression functions with multibyte character support.
</P
></LI
></UL
>
</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="mbstring.configuration"
></A
>Runtime Configuration</H1
><P
> The behaviour of these functions is affected by settings in <TT
CLASS="filename"
>php.ini</TT
>.
</P
><P
> <DIV
CLASS="table"
><A
NAME="AEN45434"
></A
><P
><B
>Table 1. Multi-Byte String configuration options</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><THEAD
><TR
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
>Name</TH
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
>Default</TH
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
>Changeable</TH
></TR
></THEAD
><TBODY
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>mbstring.language</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>NULL</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>PHP_INI_ALL</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>mbstring.detect_order</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>NULL</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>PHP_INI_ALL</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>mbstring.http_input</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>NULL</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>PHP_INI_ALL</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>mbstring.http_output</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>NULL</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>PHP_INI_ALL</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>mbstring.internal_encoding</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>NULL</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>PHP_INI_ALL</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>mbstring.script_encoding</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>NULL</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>PHP_INI_ALL</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>mbstring.substitute_character</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>NULL</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>PHP_INI_ALL</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>mbstring.func_overload</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>"0"</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>PHP_INI_SYSTEM</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>mbstring.encoding_translation</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>"0"</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>PHP_INI_ALL</TD
></TR
></TBODY
></TABLE
></DIV
>
For further details and definition of the PHP_INI_* constants see
<A
HREF="function.ini-set.html"
><B
CLASS="function"
>ini_set()</B
></A
>.
</P
><P
> Here is a short explanation of the configuration directives.
<P
></P
><UL
><LI
><A
NAME="ini.mbstring.language"
></A
><P
> <TT
CLASS="literal"
>mbstring.language</TT
> defines
default language used in mbstring.
Note that this option defines
<TT
CLASS="literal"
>mbstring.interanl_encoding</TT
>
and <TT
CLASS="literal"
>mbstring.interanl_encoding</TT
>
should be placed after <TT
CLASS="literal"
>mbstring.language</TT
>
in <TT
CLASS="filename"
>php.ini</TT
>
</P
></LI
><LI
><A
NAME="ini.mbstring.encoding-translation"
></A
><P
> <TT
CLASS="literal"
>mbstring.encoding_translation</TT
> enables
HTTP input character encoding detection and translation into
internal chatacter encoding.
</P
></LI
><LI
><A
NAME="ini.mbstring.internal-encoding"
></A
><P
> <TT
CLASS="literal"
>mbstring.internal_encoding</TT
> defines default
internal character encoding.
</P
></LI
><LI
><A
NAME="ini.mbstring.http-input"
></A
><P
> <TT
CLASS="literal"
>mbstring.http_input</TT
> defines default HTTP
input character encoding.
</P
></LI
><LI
><A
NAME="ini.mbstring.http-output"
></A
><P
> <TT
CLASS="literal"
>mbstring.http_output</TT
> defines default HTTP
output character encoding.
</P
></LI
><LI
><A
NAME="ini.mbstring.detect-order"
></A
><P
> <TT
CLASS="literal"
>mbstring.detect_order</TT
> defines default
character code detection order. See also
<A
HREF="function.mb-detect-order.html"
><B
CLASS="function"
>mb_detect_order()</B
></A
>.
</P
></LI
><LI
><A
NAME="ini.mbstring.substitute-character"
></A
><P
> <TT
CLASS="literal"
>mbstring.substitute_character</TT
> defines
character to substitute for invalid character encoding.
</P
></LI
><LI
><A
NAME="ini.mbstring.func-overload"
></A
><P
> <TT
CLASS="literal"
>mbstring.func_overload</TT
>overload(replace) single byte
functions by mbstring functions. <A
HREF="function.mail.html"
><B
CLASS="function"
>mail()</B
></A
>,
<A
HREF="function.ereg.html"
><B
CLASS="function"
>ereg()</B
></A
>, etc. are overloaded by
<A
HREF="function.mb-send-mail.html"
><B
CLASS="function"
>mb_send_mail()</B
></A
>, <A
HREF="function.mb-ereg.html"
><B
CLASS="function"
>mb_ereg()</B
></A
>, etc.
Possible values are 0, 1, 2, 4 or a combination of them.
For example, 7 for overload everything.
0: No overload, 1: Overload <A
HREF="function.mail.html"
><B
CLASS="function"
>mail()</B
></A
> function,
2: Overload str*() functions, 4: Overload ereg*() functions.
</P
></LI
></UL
>
</P
><P
> Web Browsers are supposed to use the same character encoding
when submitting form. However, browsers may not use the same
character encoding. See <A
HREF="function.mb-http-input.html"
><B
CLASS="function"
>mb_http_input()</B
></A
> to
detect character encoding used by browsers.
</P
><P
> If <TT
CLASS="literal"
>enctype</TT
> is set to
<TT
CLASS="literal"
>multipart/form-data</TT
> in HTML forms,
<TT
CLASS="literal"
>mbstring</TT
> does not convert character encoding
in POST data. The user must convert them in the script, if
conversion is needed.
</P
><P
> Although, browsers are smart enough to detect character encoding
in HTML. <TT
CLASS="literal"
>charset</TT
> is better to be set in HTTP
header. Change <TT
CLASS="literal"
>default_charset</TT
> according to
character encoding.
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN45526"
></A
><P
><B
>Example 1. <TT
CLASS="filename"
>php.ini</TT
> setting example</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>; Set default language
mbstring.language = English; Set default language to English (default)
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 to "ASCII,JIS,UTF-8,EUC-JP,SJIS"
mbstring.http_input = SJIS ; Set HTTP2 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</PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN45531"
></A
><P
><B
>Example 2. <TT
CLASS="filename"
>php.ini</TT
> setting for <TT
CLASS="literal"
>EUC-JP</TT
> users</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>;; 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</PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN45537"
></A
><P
><B
>Example 3. <TT
CLASS="filename"
>php.ini</TT
> setting for <TT
CLASS="literal"
>SJIS</TT
> users</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>;; 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</PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="mbstring.resources"
></A
>Resource Types</H1
><P
>This extension has no resource types defined.</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="mbstring.constants"
></A
>Predefined Constants</H1
><P
> The constants below are defined by this extension, and
will only be available when the extension has either
been compiled into PHP or dynamically loaded at runtime.
</P
><P
></P
><DIV
CLASS="variablelist"
><DL
><DT
><TT
CLASS="constant"
><B
>MB_OVERLOAD_MAIL</B
></TT
>
(<A
HREF="language.types.integer.html"
>integer</A
>)</DT
><DD
><P
>
</P
></DD
><DT
><TT
CLASS="constant"
><B
>MB_OVERLOAD_STRING</B
></TT
>
(<A
HREF="language.types.integer.html"
>integer</A
>)</DT
><DD
><P
>
</P
></DD
><DT
><TT
CLASS="constant"
><B
>MB_OVERLOAD_REGEX</B
></TT
>
(<A
HREF="language.types.integer.html"
>integer</A
>)</DT
><DD
><P
>
</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="mbstring.http"
></A
>HTTP Input and Output</H1
><P
> HTTP input/output character encoding conversion may convert
binary data also. Users are supposed to control character
encoding conversion if binary data is used for HTTP
input/output.
</P
><P
> If <TT
CLASS="literal"
>enctype</TT
> for HTML form is set to
<TT
CLASS="literal"
>multipart/form-data</TT
>,
<TT
CLASS="literal"
>mbstring</TT
> does not convert character encoding
in POST data. If it is the case, strings are needed to be
converted to internal character encoding.
</P
><P
> <P
></P
><UL
><LI
><P
> HTTP Input
</P
><P
>
There is no way to control HTTP input character
conversion from PHP script. To disable HTTP input character
conversion, it has to be done in <TT
CLASS="filename"
>php.ini</TT
>.
<TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN45580"
></A
><P
><B
>Example 4.
Disable HTTP input conversion in <TT
CLASS="filename"
>php.ini</TT
>
</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="php"
>;; Disable HTTP Input conversion
mbstring.http_input = pass
;; Disable HTTP Input conversion (PHP 4.3.0 or higher)
mbstring.encoding_translation = Off</PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
> When using PHP as an Apache module, it is possible to
override PHP ini setting per Virtual Host in
<TT
CLASS="literal"
>httpd.conf</TT
> or per directory with
<TT
CLASS="literal"
>.htaccess</TT
>. Refer to the <A
HREF="configuration.html"
>Configuration</A
> section and
Apache Manual for details.
</P
></LI
><LI
><P
> HTTP Output
</P
><P
> There are several ways to enable output character encoding
conversion. One is using <TT
CLASS="filename"
>php.ini</TT
>, another
is using <A
HREF="function.ob-start.html"
><B
CLASS="function"
>ob_start()</B
></A
> with
<A
HREF="function.mb-output-handler.html"
><B
CLASS="function"
>mb_output_handler()</B
></A
> as
<TT
CLASS="literal"
>ob_start</TT
> callback function.
</P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>
For PHP3-i18n users, <TT
CLASS="literal"
>mbstring</TT
>'s output
conversion differs from PHP3-i18n. Character encoding is
converted using output buffer.
</P
></BLOCKQUOTE
></DIV
></LI
></UL
>
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN45599"
></A
><P
><B
>Example 5. <TT
CLASS="filename"
>php.ini</TT
> setting example</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>;; Enable output character encoding conversion for all PHP pages
;; Enable Output Buffering
output_buffering = On
;; Set mb_output_handler to enable output conversion
output_handler = mb_output_handler</PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN45604"
></A
><P
><B
>Example 6. Script example</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="php"
><?php
// Enable output character encoding conversion only for this page
// Set HTTP output character encoding to SJIS
mb_http_output('SJIS');
// Start buffering and specify "mb_output_handler" as
// callback function
ob_start('mb_output_handler');
?></PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="mbstring.encodings"
></A
>Supported Character Encodings</H1
><P
> Currently, the following character encoding is supported by the
<TT
CLASS="literal"
>mbstring</TT
> module. Character encoding may
be specified for <TT
CLASS="literal"
>mbstring</TT
> functions'
<TT
CLASS="literal"
>encoding</TT
> parameter.
</P
><P
> The following character encoding is supported in this PHP
extension:
</P
><P
> <TT
CLASS="literal"
>UCS-4</TT
>, <TT
CLASS="literal"
>UCS-4BE</TT
>,
<TT
CLASS="literal"
>UCS-4LE</TT
>, <TT
CLASS="literal"
>UCS-2</TT
>,
<TT
CLASS="literal"
>UCS-2BE</TT
>, <TT
CLASS="literal"
>UCS-2LE</TT
>,
<TT
CLASS="literal"
>UTF-32</TT
>, <TT
CLASS="literal"
>UTF-32BE</TT
>,
<TT
CLASS="literal"
>UTF-32LE</TT
>, <TT
CLASS="literal"
>UCS-2LE</TT
>,
<TT
CLASS="literal"
>UTF-16</TT
>, <TT
CLASS="literal"
>UTF-16BE</TT
>,
<TT
CLASS="literal"
>UTF-16LE</TT
>, <TT
CLASS="literal"
>UTF-8</TT
>,
<TT
CLASS="literal"
>UTF-7</TT
>, <TT
CLASS="literal"
>ASCII</TT
>,
<TT
CLASS="literal"
>EUC-JP</TT
>, <TT
CLASS="literal"
>SJIS</TT
>,
<TT
CLASS="literal"
>eucJP-win</TT
>, <TT
CLASS="literal"
>SJIS-win</TT
>,
<TT
CLASS="literal"
>ISO-2022-JP</TT
>, <TT
CLASS="literal"
>JIS</TT
>,
<TT
CLASS="literal"
>ISO-8859-1</TT
>, <TT
CLASS="literal"
>ISO-8859-2</TT
>,
<TT
CLASS="literal"
>ISO-8859-3</TT
>, <TT
CLASS="literal"
>ISO-8859-4</TT
>,
<TT
CLASS="literal"
>ISO-8859-5</TT
>, <TT
CLASS="literal"
>ISO-8859-6</TT
>,
<TT
CLASS="literal"
>ISO-8859-7</TT
>, <TT
CLASS="literal"
>ISO-8859-8</TT
>,
<TT
CLASS="literal"
>ISO-8859-9</TT
>, <TT
CLASS="literal"
>ISO-8859-10</TT
>,
<TT
CLASS="literal"
>ISO-8859-13</TT
>, <TT
CLASS="literal"
>ISO-8859-14</TT
>,
<TT
CLASS="literal"
>ISO-8859-15</TT
>, <TT
CLASS="literal"
>byte2be</TT
>,
<TT
CLASS="literal"
>byte2le</TT
>, <TT
CLASS="literal"
>byte4be</TT
>,
<TT
CLASS="literal"
>byte4le</TT
>, <TT
CLASS="literal"
>BASE64</TT
>,
<TT
CLASS="literal"
>7bit</TT
>, <TT
CLASS="literal"
>8bit</TT
> and
<TT
CLASS="literal"
>UTF7-IMAP</TT
>.
</P
><P
> As of PHP 4.3.0, the following character encoding support will be added
experimentaly :
<TT
CLASS="literal"
>EUC-CN</TT
>, <TT
CLASS="literal"
>CP936</TT
>, <TT
CLASS="literal"
>HZ</TT
>,
<TT
CLASS="literal"
>EUC-TW</TT
>, <TT
CLASS="literal"
>CP950</TT
>, <TT
CLASS="literal"
>BIG-5</TT
>,
<TT
CLASS="literal"
>EUC-KR</TT
>, <TT
CLASS="literal"
>UHC</TT
> (<TT
CLASS="literal"
>CP949</TT
>),
<TT
CLASS="literal"
>ISO-2022-KR</TT
>,
<TT
CLASS="literal"
>Windows-1251</TT
> (<TT
CLASS="literal"
>CP1251</TT
>),
<TT
CLASS="literal"
>Windows-1252</TT
> (<TT
CLASS="literal"
>CP1252</TT
>),
<TT
CLASS="literal"
>CP866</TT
>,
<TT
CLASS="literal"
>KOI8-R</TT
>.
</P
><P
> <TT
CLASS="filename"
>php.ini</TT
> entry, which accepts encoding name,
accepts "<TT
CLASS="literal"
>auto</TT
>" and
"<TT
CLASS="literal"
>pass</TT
>" also.
<TT
CLASS="literal"
>mbstring</TT
> functions, which accepts encoding
name, and accepts "<TT
CLASS="literal"
>auto</TT
>".
</P
><P
> If "<TT
CLASS="literal"
>pass</TT
>" is set, no character
encoding conversion is performed.
</P
><P
> If "<TT
CLASS="literal"
>auto</TT
>" is set, it is expanded to
"<TT
CLASS="literal"
>ASCII,JIS,UTF-8,EUC-JP,SJIS</TT
>".
</P
><P
> See also <A
HREF="function.mb-detect-order.html"
><B
CLASS="function"
>mb_detect_order()</B
></A
>
</P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>
"Supported character encoding" does not mean that it
works as internal character code.
</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="mbstring.overload"
></A
>Overloading PHP string functions with multi byte string functions</H1
><P
> Because almost PHP application written for language using
single-byte character encoding, there are some difficulties for
multibyte string handling including japanese. Almost PHP string
functions such as <A
HREF="function.substr.html"
><B
CLASS="function"
>substr()</B
></A
> do not support
multibyte string.
</P
><P
> Multibyte extension (mbstring) has some PHP string functions
with multibyte support (ex. <A
HREF="function.substr.html"
><B
CLASS="function"
>substr()</B
></A
> supports
<A
HREF="function.mb-substr.html"
><B
CLASS="function"
>mb_substr()</B
></A
>).
</P
><P
> Multibyte extension (mbstring) also supports 'function
overloading' to add multibyte string functionality without
code modification. Using function overloading, some PHP string
functions will be oveloaded multibyte string functions.
For example, <A
HREF="function.mb-substr.html"
><B
CLASS="function"
>mb_substr()</B
></A
> is called
instead of <A
HREF="function.substr.html"
><B
CLASS="function"
>substr()</B
></A
> if function overloading
is enabled. Function overload makes easy to port application
supporting only single-byte encoding for multibyte application.
</P
><P
> <TT
CLASS="literal"
>mbstring.func_overload</TT
> in <TT
CLASS="filename"
>php.ini</TT
> should be
set some positive value to use function overloading.
The value should specify the category of overloading functions,
sbould be set 1 to enable mail function overloading. 2 to enable
string functions, 4 to regular expression functions. For
example, if is set for 7, mail, strings, regex functions should
be overloaded. The list of overloaded functions are shown in
below.
<DIV
CLASS="table"
><A
NAME="AEN45703"
></A
><P
><B
>Table 2. Functions to be overloaded</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><THEAD
><TR
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
>value of mbstring.func_overload</TH
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
>original function</TH
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
>overloaded function</TH
></TR
></THEAD
><TBODY
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>1</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.mail.html"
><B
CLASS="function"
>mail()</B
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.mb-send-mail.html"
><B
CLASS="function"
>mb_send_mail()</B
></A
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>2</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.strlen.html"
><B
CLASS="function"
>strlen()</B
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.mb-strlen.html"
><B
CLASS="function"
>mb_strlen()</B
></A
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>2</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.strpos.html"
><B
CLASS="function"
>strpos()</B
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.mb-strpos.html"
><B
CLASS="function"
>mb_strpos()</B
></A
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>2</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.strrpos.html"
><B
CLASS="function"
>strrpos()</B
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.mb-strrpos.html"
><B
CLASS="function"
>mb_strrpos()</B
></A
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>2</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.substr.html"
><B
CLASS="function"
>substr()</B
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.mb-substr.html"
><B
CLASS="function"
>mb_substr()</B
></A
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>2</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.strtolower.html"
><B
CLASS="function"
>strtolower()</B
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.mb-strtolower.html"
><B
CLASS="function"
>mb_strtolower()</B
></A
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>2</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.strtoupper.html"
><B
CLASS="function"
>strtoupper()</B
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.mb-strtoupper.html"
><B
CLASS="function"
>mb_strtoupper()</B
></A
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>2</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.substr-count.html"
><B
CLASS="function"
>substr_count()</B
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.mb-substr-count.html"
><B
CLASS="function"
>mb_substr_count()</B
></A
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>4</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.ereg.html"
><B
CLASS="function"
>ereg()</B
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.mb-ereg.html"
><B
CLASS="function"
>mb_ereg()</B
></A
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>4</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.eregi.html"
><B
CLASS="function"
>eregi()</B
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.mb-eregi.html"
><B
CLASS="function"
>mb_eregi()</B
></A
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>4</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.ereg-replace.html"
><B
CLASS="function"
>ereg_replace()</B
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.mb-ereg-replace.html"
><B
CLASS="function"
>mb_ereg_replace()</B
></A
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>4</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.eregi-replace.html"
><B
CLASS="function"
>eregi_replace()</B
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.mb-eregi-replace.html"
><B
CLASS="function"
>mb_eregi_replace()</B
></A
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>4</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.split.html"
><B
CLASS="function"
>split()</B
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="function.mb-split.html"
><B
CLASS="function"
>mb_split()</B
></A
></TD
></TR
></TBODY
></TABLE
></DIV
>
</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="mbstring.ja-basic"
></A
>Basics of Japanese multi-byte characters</H1
><P
> Most Japanese characters need more than 1 byte per character. In
addition, several character encoding schemas are used under a
Japanese environment. There are EUC-JP, Shift_JIS(SJIS) and
ISO-2022-JP(JIS) character encoding. As Unicode becomes popular,
UTF-8 is used also. To develop Web applications for a Japanese
environment, it is important to use the character set for the
task in hand, whether HTTP input/output, RDBMS and E-mail.
</P
><P
> <P
></P
><UL
><LI
><P
>Storage for a character can be up to six
bytes</P
></LI
><LI
><P
> A multi-byte character is usually twice of the width compared
to single-byte characters. Wider characters are called
"zen-kaku" - meaning full width, narrower characters are
called "han-kaku" - meaning half width. "zen-kaku" characters
are usually fixed width.
</P
></LI
><LI
><P
> Some character encoding defines shift(escape) sequence for
entering/exiting multi-byte character strings.
</P
></LI
><LI
><P
> ISO-2022-JP must be used for SMTP/NNTP.
</P
></LI
><LI
><P
> "i-mode" web site is supposed to use SJIS.
</P
></LI
></UL
>
</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="mbstring.ref"
></A
>References</H1
><P
> Multi-byte character encoding and its related issues are very
complex. It is impossible to cover in sufficient detail
here. Please refer to the following URLs and other resources for
further readings.
<P
></P
><UL
><LI
><P
> Unicode/UTF/UCS/etc
</P
><P
> <TT
CLASS="literal"
>http://www.unicode.org/</TT
>
</P
></LI
><LI
><P
> Japanese/Korean/Chinese character
information
</P
><P
> <TT
CLASS="literal"
> ftp://ftp.ora.com/pub/examples/nutshell/ujip/doc/cjk.inf
</TT
>
</P
></LI
></UL
>
</P
></DIV
></DIV
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
><A
HREF="function.mb-convert-case.html"
>mb_convert_case</A
> -- Perform case folding on a string</DT
><DT
><A
HREF="function.mb-convert-encoding.html"
>mb_convert_encoding</A
> -- Convert character encoding</DT
><DT
><A
HREF="function.mb-convert-kana.html"
>mb_convert_kana</A
> --
Convert "kana" one from another ("zen-kaku" ,"han-kaku" and more)
</DT
><DT
><A
HREF="function.mb-convert-variables.html"
>mb_convert_variables</A
> -- Convert character code in variable(s)</DT
><DT
><A
HREF="function.mb-decode-mimeheader.html"
>mb_decode_mimeheader</A
> -- Decode string in MIME header field</DT
><DT
><A
HREF="function.mb-decode-numericentity.html"
>mb_decode_numericentity</A
> --
Decode HTML numeric string reference to character
</DT
><DT
><A
HREF="function.mb-detect-encoding.html"
>mb_detect_encoding</A
> -- Detect character encoding</DT
><DT
><A
HREF="function.mb-detect-order.html"
>mb_detect_order</A
> --
Set/Get character encoding detection order
</DT
><DT
><A
HREF="function.mb-encode-mimeheader.html"
>mb_encode_mimeheader</A
> -- Encode string for MIME header</DT
><DT
><A
HREF="function.mb-encode-numericentity.html"
>mb_encode_numericentity</A
> --
Encode character to HTML numeric string reference
</DT
><DT
><A
HREF="function.mb-ereg-match.html"
>mb_ereg_match</A
> --
Regular expression match for multibyte string
</DT
><DT
><A
HREF="function.mb-ereg-replace.html"
>mb_ereg_replace</A
> -- Replace regular expression with multibyte support</DT
><DT
><A
HREF="function.mb-ereg-search-getpos.html"
>mb_ereg_search_getpos</A
> --
Returns start point for next regular expression match
</DT
><DT
><A
HREF="function.mb-ereg-search-getregs.html"
>mb_ereg_search_getregs</A
> --
Retrive the result from the last multibyte regular expression
match
</DT
><DT
><A
HREF="function.mb-ereg-search-init.html"
>mb_ereg_search_init</A
> --
Setup string and regular expression for multibyte regular
expression match
</DT
><DT
><A
HREF="function.mb-ereg-search-pos.html"
>mb_ereg_search_pos</A
> --
Return position and length of matched part of multibyte regular
expression for predefined multibyte string
</DT
><DT
><A
HREF="function.mb-ereg-search-regs.html"
>mb_ereg_search_regs</A
> --
Returns the matched part of multibyte regular expression
</DT
><DT
><A
HREF="function.mb-ereg-search-setpos.html"
>mb_ereg_search_setpos</A
> --
Set start point of next regular expression match
</DT
><DT
><A
HREF="function.mb-ereg-search.html"
>mb_ereg_search</A
> --
Multibyte regular expression match for predefined multibyte string
</DT
><DT
><A
HREF="function.mb-ereg.html"
>mb_ereg</A
> -- Regular expression match with multibyte support</DT
><DT
><A
HREF="function.mb-eregi-replace.html"
>mb_eregi_replace</A
> --
Replace regular expression with multibyte support
ignoring case
</DT
><DT
><A
HREF="function.mb-eregi.html"
>mb_eregi</A
> --
Regular expression match ignoring case with multibyte support
</DT
><DT
><A
HREF="function.mb-get-info.html"
>mb_get_info</A
> -- Get internal settings of mbstring</DT
><DT
><A
HREF="function.mb-http-input.html"
>mb_http_input</A
> -- Detect HTTP input character encoding</DT
><DT
><A
HREF="function.mb-http-output.html"
>mb_http_output</A
> -- Set/Get HTTP output character encoding</DT
><DT
><A
HREF="function.mb-internal-encoding.html"
>mb_internal_encoding</A
> --
Set/Get internal character encoding
</DT
><DT
><A
HREF="function.mb-language.html"
>mb_language</A
> --
Set/Get current language
</DT
><DT
><A
HREF="function.mb-output-handler.html"
>mb_output_handler</A
> --
Callback function converts character encoding in output buffer
</DT
><DT
><A
HREF="function.mb-parse-str.html"
>mb_parse_str</A
> --
Parse GET/POST/COOKIE data and set global variable
</DT
><DT
><A
HREF="function.mb-preferred-mime-name.html"
>mb_preferred_mime_name</A
> -- Get MIME charset string</DT
><DT
><A
HREF="function.mb-regex-encoding.html"
>mb_regex_encoding</A
> --
Returns current encoding for multibyte regex as string
</DT
><DT
><A
HREF="function.mb-regex-set-options.html"
>mb_regex_set_options</A
> --
Set/Get the default options for mbregex functions
</DT
><DT
><A
HREF="function.mb-send-mail.html"
>mb_send_mail</A
> --
Send encoded mail.
</DT
><DT
><A
HREF="function.mb-split.html"
>mb_split</A
> -- Split multibyte string using regular expression</DT
><DT
><A
HREF="function.mb-strcut.html"
>mb_strcut</A
> -- Get part of string</DT
><DT
><A
HREF="function.mb-strimwidth.html"
>mb_strimwidth</A
> -- Get truncated string with specified width</DT
><DT
><A
HREF="function.mb-strlen.html"
>mb_strlen</A
> -- Get string length</DT
><DT
><A
HREF="function.mb-strpos.html"
>mb_strpos</A
> --
Find position of first occurrence of string in a string
</DT
><DT
><A
HREF="function.mb-strrpos.html"
>mb_strrpos</A
> --
Find position of last occurrence of a string in a string
</DT
><DT
><A
HREF="function.mb-strtolower.html"
>mb_strtolower</A
> -- Make a string lowercase</DT
><DT
><A
HREF="function.mb-strtoupper.html"
>mb_strtoupper</A
> -- Make a string uppercase</DT
><DT
><A
HREF="function.mb-strwidth.html"
>mb_strwidth</A
> -- Return width of string</DT
><DT
><A
HREF="function.mb-substitute-character.html"
>mb_substitute_character</A
> -- Set/Get substitution character</DT
><DT
><A
HREF="function.mb-substr-count.html"
>mb_substr_count</A
> -- Count the number of substring occurrences</DT
><DT
><A
HREF="function.mb-substr.html"
>mb_substr</A
> -- Get part of string</DT
></DL
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="function.tanh.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="function.mb-convert-case.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>tanh</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="funcref.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>mb_convert_case</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
distrib
>
Mandriva
>
9.1
>
ppc
>
media
>
main
>
by-pkgid
>
0afeee9cca140e167a996902b9a677c5
>
files
>
3098
