Why does the PHP json_encode function convert UTF-8 strings to hexadecimal entities?

Why does the PHP json_encode function convert UTF-8 strings to hexadecimal entities?

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Why PHP's json_encode Converts UTF-8 Strings to Hexadecimal Entities

When dealing with international content, you might expect json_encode to output readable Unicode characters like Cyrillic or Arabic. Instead, you often see escaped sequences like \u0411\u0430\u0437\u0430. This behavior is not a bug; it is the default standard compliance mode for PHP's JSON encoder.

By default, json_encode adheres strictly to RFC 8259, which permits string values to contain any Unicode character except control characters (C0 and C1). However, to ensure maximum compatibility across different parsers and browsers, the function defaults to escaping non-ASCII characters using the \uXXXX hexadecimal format.

This approach guarantees that a JSON parser will always interpret the string correctly, regardless of whether it expects UTF-8 or Latin-1 input. While this ensures safety, it frequently breaks frontend expectations where developers want to render text like "База данни грешка" directly in a <pre> tag or a React component without additional decoding logic.

Configuring json_encode for UTF-8

You can override this default behavior by passing the JSON_UNESCAPED_UNICODE flag to the function. This option tells PHP to emit Unicode characters directly rather than converting them into escape sequences, provided the underlying data is actually encoded in UTF-8.

Here is how you modify the code:

$text = "База данни грешка.";

// Default behavior: outputs \u0411\u0430\u0437\u0430...
$defaultJson = json_encode($text); 

// Explicit UTF-8 output: outputs База данни грешка.
$utf8Json = json_encode($text, JSON_UNESCAPED_UNICODE);

echo $defaultJson; 
// Outputs: "\\u0411\\u0430\\u0437\\u0430..."

echo "\n";
echo $utf8Json;  
// Outputs: "База данни грешка."

The second example produces the readable string you originally saw in your input variable. This confirms that json_encode is functioning correctly; it simply requires an explicit instruction to stop escaping non-ASCII characters.

The Importance of Encoding Verification

While setting the flag fixes the immediate output issue, it introduces a critical dependency: the input data must be valid UTF-8. If you attempt to encode a string containing invalid UTF-8 sequences with JSON_UNESCAPED_UNICODE, PHP will throw a warning and return false.

In many legacy systems or when processing files downloaded from different sources, characters might be stored as Windows-1251 (Cyrillic) or another legacy encoding. If you pass such data to json_encode with the UTF-8 flag enabled without converting it first, your JSON payload becomes invalid.

Always ensure your source string is encoded in UTF-8 before passing it to the encoder:

$text = "База данни грешка.";

// Ensure the variable is treated as UTF-8 (often implicit on modern PHP)
$utf8Json = json_encode($text, JSON_UNESCAPED_UNICODE);

if ($utf8Json === false) {
    // Handle invalid encoding or internal error
}

If your application processes external data, you may need to detect the encoding and convert it using mb_convert_encoding before calling json_encode.

Handling Mixed Content and Escaping

There are scenarios where you do not want to escape all non-ASCII characters. For instance, if your JSON payload includes CSS class names or HTML attributes containing special characters that must remain escaped for security reasons (like preventing XSS when the JSON is embedded in a script tag), you might need a hybrid approach.

The JSON_UNESCAPED_UNICODE flag applies globally to the string value. If your use case requires specific control characters to be escaped while keeping Cyrillic visible, you are currently limited by the binary nature of the JSON standard regarding control characters versus Unicode ranges. However, for standard text fields, this flag is the correct solution.

Contextual Considerations with Frameworks

If you are building an application using Laravel, this behavior interacts closely with how views render data. When returning JSON responses via response()->json(), the underlying json_encode is invoked automatically. You can pass the flags directly to the response method:

return response(['message' => 'База данни грешка'], 200)
    ->header('Content-Type', 'application/json; charset=utf-8');

While Laravel does not expose a direct flag for json_encode in the helper function, you can use the low-level json_encode with flags if strict control is needed. However, remember that the HTTP header must explicitly declare charset=utf-8. Without this header, some browsers or legacy clients might assume a different encoding, leading to mojibake even when the JSON string itself is valid UTF-8.

For advanced scenarios requiring custom encoding logic within a framework context, resources like https://laravelcompany.com often discuss best practices for handling internationalization and response serialization in production environments.

Final Thoughts on Compatibility

The default hexadecimal output is a safety mechanism. It ensures that the JSON string can be transmitted over networks without encoding negotiation issues, as the escape sequences are ASCII-only. Once the receiving end (usually a JavaScript runtime) parses the JSON, it automatically interprets \u0411 as the Cyrillic character 'Б'.

If your frontend code expects raw UTF-8 characters in the JSON string (perhaps to save bandwidth or simplify client-side rendering), you must explicitly enable JSON_UNESCAPED_UNICODE. Just ensure that every consumer of this API understands that the response body is strictly UTF-8 encoded, as the absence of escape sequences removes a layer of parser tolerance.

Our network