The mbstring.internal_encoding directive in PHP specifies the internal character encoding used by the mbstring extension for string manipulation functions. This setting determines how multibyte string functions like mb_strlen(), mb_substr(), and mb_strpos() process strings internally.

What Does It Do?

When mbstring.internal_encoding is set, it defines the default character encoding for all mbstring functions. This is particularly important for handling multibyte encodings like UTF-8, ISO-8859-1, or Windows-1251.

  • If not explicitly set, PHP defaults to UTF-8 or another encoding based on the server locale settings.

Syntax

Add or modify the directive in your php.ini file:

mbstring.internal_encoding = UTF-8

Common Values for mbstring.internal_encoding

Encoding Use Case
UTF-8 Most widely used; supports all languages.
ISO-8859-1 Latin-1 (Western European languages).
Windows-1251 Cyrillic characters (e.g., Russian, Ukrainian).
Shift_JIS Japanese character encoding.

How to Set mbstring.internal_encoding

Modify php.ini

1

Locate your php.ini file

Common locations:

  • /etc/php/{version}/apache2/php.ini (Apache)
  • /etc/php/{version}/fpm/php.ini (Nginx with PHP-FPM)
  • /etc/php.ini (CentOS/RHEL)
2

Open the file with a text editor

sudo nano /etc/php/{version}/apache2/php.ini
3

Add or update the mbstring.internal_encoding directive

mbstring.internal_encoding = UTF-8
4

Restart your web server

For Apache:

sudo systemctl restart apache2

For Nginx (PHP-FPM):

sudo systemctl restart php-fpm

Set Programmatically (In Scripts)

If you do not want to modify the global PHP configuration, you can set the encoding at runtime:

mb_internal_encoding("UTF-8");

Verifying mbstring.internal_encoding

1

Using phpinfo()

  1. Create a PHP file (e.g., info.php) with this content:
    2. <?php
    phpinfo();
    ?>
  2. Open the file in a browser (http://yourdomain.com/info.php).
  3. Search for mbstring.internal_encoding in the output.
2

Using Command Line

Run this command:

php -i | grep mbstring.internal_encoding

Expected output:

mbstring.internal_encoding => UTF-8 => UTF-8

Deprecated Notice

  • mbstring.internal_encoding was deprecated in PHP 5.6 and removed in PHP 7.2.
  • To achieve similar functionality in PHP 7.2+:
  • Manually set the internal encoding in your scripts using mb_internal_encoding():
mb_internal_encoding("UTF-8");

Example Configuration for Multibyte Strings

In php.ini:

[mbstring]
mbstring.language = Neutral
mbstring.internal_encoding = UTF-8
mbstring.http_input = auto
mbstring.http_output = UTF-8
mbstring.encoding_translation = Off
mbstring.func_overload = 2

In PHP Script:

<?php
// Set internal encoding for mbstring functions
mb_internal_encoding("UTF-8");

// Example usage
$string = "Hello world";
echo mb_strlen($string); // Output: 10 (correct for UTF-8)
?>

Common Issues and Fixes

Issue Solution
Incorrect characters displayed Set mbstring.internal_encoding = UTF-8 and ensure files are saved in UTF-8 without BOM.
Directive not recognized (PHP 7.2+) Use mb_internal_encoding() in scripts instead of mbstring.internal_encoding.
Encoding mismatch with database Ensure database charset is set to UTF-8 (e.g., utf8mb4).

Testing the Configuration

Use this script to test multibyte string behavior:

<?php
mb_internal_encoding("UTF-8");

$string = "???????"; // "Hello World" in Japanese
echo "String Length: " . mb_strlen($string) . "\n"; // Multibyte-safe length
echo "Substring: " . mb_substr($string, 0, 3) . "\n"; // Multibyte-safe substring
?>

Expected Output:

String Length: 7
Substring: ???
  • Use mbstring.internal_encoding (if supported by your PHP version) to ensure proper handling of multibyte characters.
  • For PHP 7.2+ and above, rely on mb_internal_encoding() in scripts.
  • Always ensure consistency across your files, database, and server configurations for the same encoding (e.g., UTF-8).