LII. Multi-Byte String Functions

Introduction

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. mbstring is developed to handle Japanese characters. However, many mbstring functions are able to handle character encoding other than Japanese.

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.

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 mbstring.internal_encoding to a character encoding that works with PHP.

PHP4 Character Encoding Requirements

These are examples of internal character encoding that works with PHP and does NOT work with PHP.

Character encoding, that does not work with PHP, may be converted with mbstring's HTTP input/output conversion feature/function.

Note: SJIS should not be used for internal encoding unless the reader is familiar with parser/compiler, character encoding and character encoding issues.

Note: If you use database with PHP, it is recommended that you use the same character encoding for both database and internal encoding for ease of use and better performance.

If you are using PostgreSQL, it supports character encoding that is different from backend character encoding. See the PostgreSQL manual for details.

How to Enable mbstring

mbstring is an extended module. You must enable module with configure script. Refer to the Install section for details.

The following configure options are related to mbstring module.

  • --enable-mbstring : Enable mbstring functions. This option is required to use mbstring functions.

  • --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.

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.

If enctype for HTML form is set to multipart/form-data, mbstring does not convert character encoding in POST data. If it is the case, strings are needed to be converted to internal character encoding.

php.ini settings

Web Browsers are supposed to use the same character encoding when submitting form. However, browsers may not use the same character encoding. See mb_http_input() to detect character encoding used by browsers.

If enctype is set to multipart/form-data in HTML forms, mbstring does not convert character encoding in POST data. The user must convert them in the script, if conversion is needed.

Although, browsers are smart enough to detect character encoding in HTML. charset is better to be set in HTTP header. Change default_charset according to character encoding.

Overload of PHP string functions by mbstring functions with multibyte support

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 substr() do not support multibyte string.

Multibyte extension (mbstring) has some PHP string functions with multibyte support (ex. substr() supports mb_substr()).

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, mb_substr() is called instead of substr() if function overloading is enabled. Function overload makes easy to port application supporting only single-byte encoding for multibyte application.

mbstring.func_overload in php.ini 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.

Table of Contents
mb_language --  Set/Get current language
mb_parse_str --  Parse GET/POST/COOKIE data and set global variable
mb_internal_encoding --  Set/Get internal character encoding
mb_http_input -- Detect HTTP input character encoding
mb_http_output -- Set/Get HTTP output character encoding
mb_detect_order --  Set/Get character encoding detection order
mb_substitute_character -- Set/Get substitution character
mb_output_handler --  Callback function converts character encoding in output buffer
mb_preferred_mime_name -- Get MIME charset string
mb_strlen -- Get string length
mb_strpos --  Find position of first occurrence of string in a string
mb_strrpos --  Find position of last occurrence of a string in a string
mb_substr -- Get part of string
mb_strcut -- Get part of string
mb_strwidth -- Return width of string
mb_strimwidth -- Get truncated string with specified width
mb_convert_encoding -- Convert character encoding
mb_detect_encoding -- Detect character encoding
mb_convert_kana --  Convert "kana" one from another ("zen-kaku" ,"han-kaku" and more)
mb_encode_mimeheader -- Encode string for MIME header
mb_decode_mimeheader -- Decode string in MIME header field
mb_convert_variables -- Convert character code in variable(s)
mb_encode_numericentity --  Encode character to HTML numeric string reference
mb_decode_numericentity --  Decode HTML numeric string reference to character
mb_send_mail --  Send encoded mail.
mb_get_info -- Get internal settings of mbstring
mb_regex_encoding --  Returns current encoding for multibyte regex as string
mb_ereg -- Regular expression match with multibyte support
mb_eregi --  Regular expression match ignoring case with multibyte support
mb_ereg_replace -- Replace regular expression with multibyte support
mb_eregi_replace --  Replace regular expression with multibyte support ignoring case
mb_split -- Split multibyte string using regular expression
mb_ereg_match --  Regular expression match for multibyte string
mb_ereg_search --  Multibyte regular expression match for predefined multibyte string
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_init --  Setup string and regular expression for multibyte regular expression match
mb_ereg_search_getregs --  Retrive the result from the last multibyte regular expression match
mb_ereg_search_getpos --  Returns start point for next regular expression match
mb_ereg_search_setpos --  Set start point of next regular expression match