简介

While there are many languages in which every necessary character can be represented by a one-to-one mapping to an 8-bit value, there are also several languages which require so many characters for written communication that they cannot be contained within the range a mere byte can code (A byte is made up of eight bits. Each bit can contain only two distinct values, one or zero. Because of this, a byte can only represent 256 unique values (two to the power of eight)). Multibyte character encoding schemes were developed to express 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 multibyte specific string functions that help you deal with multibyte encodings in PHP. In addition to that, mbstring handles character encoding conversion between the possible encoding pairs. mbstring is designed to handle Unicode-based encodings such as UTF-8 and UCS-2 and many single-byte encodings for convenience (listed below).

JIS, SJIS, ISO-2022-JP, BIG-5

   

安装

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.

运行时配置

这些函数的行为受 php.ini 的影响。

以下是配置选项的简要解释。

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.

; 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

 

;; 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  

 

;; 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 中，或者在运行时被动态加载后才有效。

HTTP Input and Output

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.

;; 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

   

Supported Character Encodings

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 encodings are supported in this PHP extension:

Any php.ini entry which accepts an encoding name can also use the values "auto" and "pass". mbstring functions which accept an encoding name can also use the value "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()

Function Overloading Feature

You might often find it difficult to get an existing PHP application to work in a given multibyte environment. This happens because most 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 a '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 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 it is set to 7, mail, strings and regular expression functions will be overloaded. The list of overloaded functions are shown below.

注意: 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.

Basics of Japanese multi-byte encodings

Japanese characters can only be represented by multibyte encodings, and multiple encoding standards are used depending on platform and text purpose. To make matters worse, these encoding standards differ slightly from one another. In order to create a web application which would be usable in a Japanese environment, a developer has to keep these complexities in mind to ensure that the proper character encodings are used.

References

Multibyte character encoding schemes and their related issues are fairly complicated, and are beyond the scope of this documentation. Please refer to the following URLs and other resources for further information regarding these topics.

Summaries of supported encodings

目录

mb_check_encoding Check if the string is valid for the specified encoding

mb_convert_case Perform case folding on a string

mb_convert_encoding Convert character encoding

mb_convert_kana Convert "kana" one from another ("zen-kaku", "han-kaku" and more)

mb_convert_variables Convert character code in variable(s)

mb_decode_mimeheader Decode string in MIME header field

mb_decode_numericentity Decode HTML numeric string reference to character

mb_detect_encoding Detect character encoding

mb_detect_order Set/Get character encoding detection order

mb_encode_mimeheader Encode string for MIME header

mb_encode_numericentity Encode character to HTML numeric string reference

mb_ereg_match Regular expression match for multibyte string

mb_ereg_replace Replace regular expression with multibyte support

mb_ereg_search_getpos Returns start point for next regular expression match

mb_ereg_search_getregs Retrieve the result from the last multibyte regular expression match

mb_ereg_search_init Setup string and regular expression for multibyte regular expression match

mb_ereg_search_pos Return position and length of matched part of multibyte regular expression for predefined multibyte string

mb_ereg_search_regs Returns the matched part of multibyte regular expression

mb_ereg_search_setpos Set start point of next regular expression match

mb_ereg_search Multibyte regular expression match for predefined multibyte string

mb_ereg Regular expression match with multibyte support

mb_eregi_replace Replace regular expression with multibyte support ignoring case

mb_eregi Regular expression match ignoring case with multibyte support

mb_get_info Get internal settings of mbstring

mb_http_input Detect HTTP input character encoding

mb_http_output Set/Get HTTP output character encoding

mb_internal_encoding Set/Get internal character encoding

mb_language Set/Get current language

mb_list_encodings_alias_names Returns an array of all supported alias encodings

mb_list_encodings Returns an array of all supported encodings

mb_list_mime_names Returns an array or string of all supported mime names

mb_output_handler Callback function converts character encoding in output buffer

mb_parse_str Parse GET/POST/COOKIE data and set global variable

mb_preferred_mime_name Get MIME charset string

mb_regex_encoding Returns current encoding for multibyte regex as string

mb_regex_set_options Set/Get the default options for mbregex functions

mb_send_mail Send encoded mail

mb_split Split multibyte string using regular expression

mb_strcut Get part of string

mb_strimwidth Get truncated string with specified width

mb_stripos Finds position of first occurrence of a string within another, case insensitive

mb_stristr Finds first occurrence of a string within another, case insensitive

mb_strlen Get string length

mb_strpos Find position of first occurrence of string in a string

mb_strrchr Finds the last occurrence of a character in a string within another

mb_strrichr Finds the last occurrence of a character in a string within another, case insensitive

mb_strripos Finds position of last occurrence of a string within another, case insensitive

mb_strrpos Find position of last occurrence of a string in a string

mb_strstr Finds first occurrence of a string within another

mb_strtolower Make a string lowercase

mb_strtoupper Make a string uppercase

mb_strwidth Return width of string

mb_substitute_character Set/Get substitution character

mb_substr_count Count the number of substring occurrences

mb_substr Get part of string