Decode base64 string - php

Decode base64 string - php

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

Stefan Bogdanescu

Founder & Senior Architect

Decoding Base64 Strings Encoded with ISO-2022-JP

When you encounter a Base64 string that refuses to decode into readable text, the issue often isn't the decoding algorithm itself, but the character encoding used before the Base64 transformation. In your specific case, the string GyRCQjZCPjhsOEBCLDtuGyhCIC0gdGVzdGluZw== is wrapped in a MIME header format:

"=?iso-2022-jp?B?..."

This format indicates that the data inside the Base64 payload (B) was originally encoded using the iso-2022-jp character set. A standard base64_decode() call in PHP will successfully convert the Base64 characters back to raw bytes, but if you output those bytes directly via echo, they may appear as garbled text or mojibake because your terminal or browser expects UTF-8 by default.

The core problem is a mismatch between the encoding declared in the header (iso-2022-jp) and the encoding assumed by the decoder (usually UTF-8). To retrieve the original Chinese string "語言測試 - testing", you must explicitly tell PHP to interpret the raw bytes using the correct charset.

The Correct Approach in PHP

The mb_convert_encoding() function is designed exactly for this scenario. It accepts the source encoding and converts the data to your desired output encoding, typically UTF-8.

Here is how you should modify your decoding logic:

<?php
$encodedString = 'GyRCQjZCPjhsOEBCLDtuGyhCIC0gdGVzdGluZw=='; // The Base64 payload only
$charsetFromHeader = 'iso-2022-jp';
$charsetToOutput = 'UTF-8';

// Decode Base64 first
$rawBytes = base64_decode($encodedString);

// Convert character encoding from ISO-2022-JP to UTF-8
$decodedString = mb_convert_encoding($rawBytes, $charsetToOutput, $charsetFromHeader);

echo $decodedString; 
?>

By passing the raw bytes (the output of base64_decode) into mb_convert_encoding with the source set to iso-2022-jp, PHP correctly maps the byte sequences to their corresponding Chinese characters. This results in the readable string: 語言測試 - testing.

Understanding MIME Headers

The full header you received, =?iso-2022-jp?B?GyRCQjZCPjhsOEBCLDtuGyhCIC0gdGVzdGluZw==?= follows the standard MIME header format defined in RFC 2047. It consists of three parts:

  1. =?...?=: Indicates a continuation or encoded word.
  2. iso-2022-jp: Specifies the character set (in this case, an older Japanese encoding that supports CJK characters).
  3. B: Specifies Base64 transfer encoding.

Many modern systems default to UTF-8 for email subjects and headers. When a system receives a message with an ISO-2022-JP encoded header but assumes the content is UTF-8, it attempts to interpret the bytes directly, leading to incorrect character mappings. This is why online decoders that assume UTF-8 input fail; they are missing the crucial piece of metadata provided in your original string: the charset declaration.

Handling Raw MIME Headers

If you are parsing raw email headers where the full =?...?= string is present rather than just the Base64 payload, you need to strip the wrapper before processing. A regular expression can isolate the Base64 part efficiently:

$fullHeader = '=?iso-2022-jp?B?GyRCQjZCPjhsOEBCLDtuGyhCIC0gdGVzdGluZw==?=';

// Extract only the Base64 content between the ?B? markers
if (preg_match('/\?=([A-Za-z-]+)\?B\?(.+?)\?=/i', $fullHeader, $matches)) {
    $charset = $matches[1];
    $payload = $matches[2];

    $rawBytes = base64_decode($payload);
    $finalString = mb_convert_encoding($rawBytes, 'UTF-8', $charset);
    
    echo $finalString;
}

Why This Matters for Legacy Systems

While iso-2022-jp is largely obsolete in modern web development in favor of UTF-8, it remains common in legacy email systems and older Japanese software environments. Failing to handle these encodings correctly results in data loss or unreadable subject lines. When integrating with external APIs or email clients that utilize non-UTF-8 standards, always inspect the character set declaration within MIME headers before attempting to decode Base64 content.

If you are building a robust application that handles mixed encoding environments, consider using a library like php-imap or similar tools that often handle these header parsing complexities internally, though understanding the underlying mechanics ensures you can debug issues when standard libraries fall short.

Our network