While there are many languages in which every necessary character can be represented by a one-to-one mapping to a 8-bit value, there are also several languages which require so many characters for written communication that cannot be contained within the range a mere byte can code. Multibyte character encoding schemes were developed to express that many (more than 256) characters in the regular bytewise coding system.
When you manipulate (trim, split, splice, etc.) strings encoded in a multibyte encoding, you need to use special functions since two or more consecutive bytes may represent a single character in such encoding schemes. Otherwise, if you apply a non-multibyte-aware string function to the string, it probably fails to detect the beginning or ending of the multibyte character and ends up with a corrupted garbage string that most likely loses its original meaning.
mbstring
provides these multibyte specific
string functions that help you deal with multibyte encodings in PHP,
which is basically supposed to be used with single byte encodings.
In addition to that, mbstring
handles character
encoding conversion between the possible encoding pairs.
mbstring
is also designed to handle Unicode-based
encodings such as UTF-8 and UCS-2 and many single-byte encodings
for convenience (listed below), whereas mbstring
was
originally developed for use in Japanese web pages.
Encodings of the following types are safely used with PHP.
A singlebyte encoding,
00h
to
7fh
.
A multibyte encoding,
00h
to 7fh
.
00h
to
7fh
in any of the compounded bytes
that represents a single character.
These are examples of character encodings that are unlikely to work with PHP.
JIS, SJIS, ISO-2022-JP, BIG-5
Although PHP scripts written in any of those encodings might not work,
especially in the case where encoded strings appear as identifiers
or literals in the script, you can almost avoid using these encodings
by setting up the mbstring
's transparent encoding
filter function for incoming HTTP queries.
It's highly discouraged to use SJIS, BIG5, CP936, CP949 and GB18030 for the internal encoding unless you are familiar with the parser, the scanner and the character encoding.
If you have some database connected with PHP, it is recommended that
you use the same character encoding for both database and the
internal encoding
for ease of use and better
performance.
If you are using PostgreSQL, the character encoding used in the database and the one used in the PHP may differ as it supports automatic character set conversion between the backend and the frontend.
mbstring
is a non-default extension. This means it
is not enabled by default. You must explicitly enable the module with
the configure
option. See the
Install section for details.
The following configure options are related to the
mbstring
module.
--enable-mbstring=LANG
: Enable
mbstring
functions. This option is
required to use mbstring
functions.
As of PHP 4.3.0, mbstring
extension provides
enhanced support for Simplified Chinese, Traditional Chinese,
Korean, and Russian in addition to Japanese.
To enable that feature, you will have to supply either one of the
following options to the LANG
parameter;
--enable-mbstring=cn
for Simplified Chinese support,
--enable-mbstring=tw
for Traditional Chinese support,
--enable-mbstring=kr
for Korean support,
--enable-mbstring=ru
for Russian support, and
--enable-mbstring=ja
for Japanese support.
Also --enable-mbstring=all
is
convenient for you to enable all the supported languages listed above.
Japanese language support is also enabled by
--enable-mbstring
without any options
for the sake of backwards compatibility.
--enable-mbstr-enc-trans
:
Enable HTTP input character encoding conversion using
mbstring
conversion engine. If this
feature is enabled, HTTP input character encoding may be
converted to mbstring.internal_encoding
automatically.
As of PHP 4.3.0, the option
--enable-mbstr-enc-trans
was eliminated and replaced with the runtime setting
mbstring.encoding_translation
.
HTTP input character encoding conversion is enabled
when this is set to On
(the default is Off
).
--enable-mbregex
: Enable
regular expression functions with multibyte character support.
这些函数的行为受 php.ini
的影响。
Name | Default | Changeable | Changelog |
---|---|---|---|
mbstring.language | "neutral" | PHP_INI_PERDIR | Available since PHP 4.3.0. |
mbstring.detect_order | NULL | PHP_INI_ALL | Available since PHP 4.0.6. |
mbstring.http_input | "pass" | PHP_INI_ALL | Available since PHP 4.0.6. |
mbstring.http_output | "pass" | PHP_INI_ALL | Available since PHP 4.0.6. |
mbstring.internal_encoding | NULL | PHP_INI_ALL | Available since PHP 4.0.6. |
mbstring.script_encoding | NULL | PHP_INI_ALL | Available since PHP 4.3.0. |
mbstring.substitute_character | NULL | PHP_INI_ALL | Available since PHP 4.0.6. |
mbstring.func_overload | "0" | PHP_INI_PERDIR | PHP_INI_SYSTEM in PHP <= 4.2.3. Available since PHP 4.2.0. |
mbstring.encoding_translation | "0" | PHP_INI_PERDIR | Available since PHP 4.3.0. |
For the definition of the PHP_INI_* constants, please refer to ini_set().
以下是配置选项的简要解释。
The default national language setting (NLS) used in mbstring. Note that this option
automagically defines mbstring.internal_encoding
and
mbstring.internal_encoding
should be placed
after mbstring.language
in php.ini
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.
Defines the default internal character encoding.
Defines the default HTTP input character encoding.
Defines the default HTTP output character encoding.
Defines default character code detection order. See also mb_detect_order().
Defines character to substitute for invalid character encoding.
Overloads a set of single byte functions by the mbstring counterparts. See Function overloading for more information.
According to the » HTML 4.01 specification, Web browsers are allowed to encode a form being submitted with a character encoding different from the one used for the page. See mb_http_input() to detect character encoding used by browsers.
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 charset
parameter in the
Content-Type
HTTP header to the appropriate value by
header() or
default_charset ini setting.
php.ini
setting examples; 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 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
php.ini
setting for EUC-JP users;; 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
php.ini
setting for SJIS users;; 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
以下常量由本扩展模块定义,因此只有在本扩展模块被编译到 PHP 中,或者在运行时被动态加载后才有效。
MB_OVERLOAD_MAIL
(integer)
MB_OVERLOAD_STRING
(integer)
MB_OVERLOAD_REGEX
(integer)
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.
In PHP 4.3.2 or earlier versions, there was a limitation in this
functionality that mbstring
does not perform
character encoding conversion in POST data if the
enctype
attribute in the form
element is set to multipart/form-data
.
So you have to convert the incoming data by yourself in this case
if necessary.
Beginning with PHP 4.3.3, if enctype
for HTML form is
set to multipart/form-data
and
mbstring.encoding_translation
is set to On
in php.ini
the POST'ed variables and the names of uploaded files
will be converted to the internal character encoding as well.
However, the conversion isn't applied to the query keys.
HTTP Input
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 php.ini
.
php.ini
;; Disable HTTP Input conversion
mbstring.http_input = pass
;; Disable HTTP Input conversion (PHP 4.3.0 or higher)
mbstring.encoding_translation = Off ?>
When using PHP as an Apache module, it is possible to
override those settings in each Virtual Host directive in
httpd.conf
or per directory with .htaccess
. Refer to the Configuration section and
Apache Manual for details.
HTTP Output
There are several ways to enable output character encoding
conversion. One is using php.ini
, another
is using ob_start() with
mb_output_handler() as
ob_start
callback function.
PHP3-i18n users should note that mbstring
's output
conversion differs from PHP3-i18n. Character encoding is
converted using output buffer.
php.ini
setting example;; 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
Currently the following character encodings are supported by the
mbstring
module. Any of those Character encodings
can be specified in the encoding
parameter of
mbstring
functions.
The following character encoding is supported in this PHP extension:
php.ini
entry, which accepts encoding name,
accepts "auto
" and
"pass
" also.
mbstring
functions, which accepts encoding
name, and accepts "auto
".
If "pass
" is set, no character
encoding conversion is performed.
If "auto
" is set, it is expanded to
the list of encodings defined per the NLS.
For instance, if the NLS is set to Japanese
,
the value is assumed to be
"ASCII,JIS,UTF-8,EUC-JP,SJIS
".
See also mb_detect_order()
You might often find it difficult to get an existing PHP application work in a given multibyte environment. That's mostly because lots of PHP applications out there are written with the standard string functions such as substr(), which are known to not properly handle multibyte-encoded strings.
mbstring supports 'function overloading' feature which enables you to add multibyte awareness to such an application without code modification by overloading multibyte counterparts on the standard string functions. For example, mb_substr() is called instead of substr() if function overloading is enabled. This feature makes it easy to port applications that only support single-byte encodings to a multibyte environment in many cases.
To use the function overloading, set
mbstring.func_overload
in php.ini
to a
positive value that represents a combination of bitmasks specifying
the categories of functions to be overloaded. It should be set
to 1 to overload the mail() function. 2 for string
functions, 4 for regular expression functions. For example,
if is set for 7, mail, strings and regular expression functions should
be overloaded. The list of overloaded functions are shown below.
value of mbstring.func_overload | original function | overloaded function |
---|---|---|
1 | mail() | mb_send_mail() |
2 | strlen() | mb_strlen() |
2 | strpos() | mb_strpos() |
2 | strrpos() | mb_strrpos() |
2 | substr() | mb_substr() |
2 | strtolower() | mb_strtolower() |
2 | strtoupper() | mb_strtoupper() |
2 | substr_count() | mb_substr_count() |
4 | ereg() | mb_ereg() |
4 | eregi() | mb_eregi() |
4 | ereg_replace() | mb_ereg_replace() |
4 | eregi_replace() | mb_eregi_replace() |
4 | split() | mb_split() |
It is not recommended to use the function overloading option in the per-directory context, because it's not confirmed yet to be stable enough in a production environment and may lead to undefined behaviour.
It is often said quite hard to figure out how Japanese texts are handled in the computer. This is not only because Japanese characters can only be represented by multibyte encodings, but because different encoding standards are adopted for different purposes / platforms. Moreover, not a few character set standards are used there, which are slightly different from one another. Those facts have often led developers to inevitable mess-up.
To create a working web application that would be put in the Japanese environment, it is important to use the proper character encoding and character set for the task in hand.
00h
to 7fh
).
Multibyte character encoding schemes and the related issues are very complicated. There should be too few space to cover in sufficient details. Please refer to the following URLs and other resources for further readings.
Unicode materials
Japanese/Korean/Chinese character information
UCS-4
, strings are always assumed
to be in big endian form.
UCS-4
, strings are always assumed
to be in little endian form.
UCS-2
, strings are always assumed
to be in big endian form.
UCS-2
, strings are always assumed
to be in little endian form.
UTF-32
, strings are always assumed
to be in big endian form.
UTF-32
, strings are always assumed
to be in little endian form.
UTF-16
, strings are always assumed
to be in big endian form.
UTF-16
, strings are always assumed
to be in big endian form.
目录