【PHP8.x】mb_internal_encoding関数の使い方

<?php

declare(strict_types=1);

/**
 * mb_internal_encoding の設定ミスや不正な引数によるエラーの例を示します。
 *
 * この関数は、多くの mbstring 関数がデフォルトで使用する文字エンコーディングを設定します。
 * 1. 実際のデータと異なるエンコーディングを設定すると、文字化けなど予期せぬ結果（エラー）の原因となります。
 * 2. 存在しないエンコーディング名を指定すると、PHP 8.0 以降は ValueError がスローされます。
 */
function demonstrateMbInternalEncodingError(): void
{
    // このスクリプトファイルの文字エンコーディングは UTF-8 であるとします。
    $utf8String = 'こんにちは世界';

    echo "元の文字列: " . $utf8String . PHP_EOL;
    echo "現在の内部エンコーディング: " . mb_internal_encoding() . PHP_EOL;
    echo "----------------------------------------" . PHP_EOL;

    // --- ケース1: 内部エンコーディングと実際のデータが不一致な場合 ---
    echo "【エラーケース1】内部エンコーディングを Shift_JIS に設定 (データはUTF-8)" . PHP_EOL;

    // 内部エンコーディングを、実際のデータ(UTF-8)とは異なる Shift_JIS に設定します。
    if (mb_internal_encoding('Shift_JIS')) {
        echo "内部エンコーディングを 'Shift_JIS' に変更しました。" . PHP_EOL;

        // この状態で mb_substr を使うと、マルチバイト文字を正しく認識できず、文字化けします。
        // これが設定ミスによる代表的なエラーです。
        $result = mb_substr($utf8String, 0, 5);
        echo "mb_substr の結果: " . $result . " (※文字化けが発生)" . PHP_EOL;
        echo PHP_EOL;
    }

    // --- ケース2: 内部エンコーディングを正しく設定した場合 ---
    echo "【正常ケース】内部エンコーディングを UTF-8 に設定 (データもUTF-8)" . PHP_EOL;

    // 内部エンコーディングをデータに合わせて UTF-8 に戻します。
    if (mb_internal_encoding('UTF-8')) {
        echo "内部エンコーディングを 'UTF-8' に変更しました。" . PHP_EOL;

        // 正しく設定されているため、mb_substr は期待通りに動作します。
        $result = mb_substr($utf8String, 0, 5);
        echo "mb_substr の結果: " . $result . " (※正常に5文字取得)" . PHP_EOL;
        echo "----------------------------------------" . PHP_EOL;
    }

    // --- ケース3: 無効なエンコーディング名を指定した場合のエラー ---
    echo "【エラーケース2】無効なエンコーディング名を指定" . PHP_EOL;

    try {
        // 存在しないエンコーディング名を指定すると、ValueError がスローされます。
        // (PHP 7以前では E_WARNING が発生し、false が返ります)
        echo "無効なエンコーディング 'INVALID_ENCODING' を設定しようとします..." . PHP_EOL;
        mb_internal_encoding('INVALID_ENCODING');
    } catch (ValueError $e) {
        // 例外をキャッチしてエラーメッセージを表示します。
        echo "エラーをキャッチしました: " . $e->getMessage() . PHP_EOL;
    }
}

// 関数を実行してデモを表示します。
demonstrateMbInternalEncodingError();

mb_internal_encodingは、PHPが文字列を扱う際の基準となる内部文字エンコーディングを設定、または取得するための関数です。引数に'UTF-8'などのエンコーディング名を文字列で渡すと設定モードになり、成功するとtrueを返します。引数を省略した場合は現在の設定値が文字列として返されます。

このサンプルコードは、本関数の使用時に起こりうる代表的な2つのエラーパターンを解説しています。1つ目は、設定した内部エンコーディングと、実際に処理する文字列データのエンコーディングが一致しないケースです。コード例のように、UTF-8の文字列をShift_JISとして扱おうとすると、mb_substrのようなマルチバイト文字列関数が正しく動作せず、文字化けという予期せぬ結果を引き起こします。

2つ目は、引数に存在しないエンコーディング名を指定するケースです。PHP 8.0以降、この操作はValueErrorという例外エラーを発生させます。コードではtry-catch構文を使い、プログラムが停止しないようにこのエラーを適切に捕捉しています。日本語などのマルチバイト文字を扱う際には、エンコーディングを正しく意識して設定することが不可欠です。

<?php

/**
 * PHPの内部文字エンコーディングの取得と設定を実演します。
 *
 * mb_internal_encoding関数は、マルチバイト文字列の処理において、
 * アプリケーション全体で使用するデフォルトのエンコーディングを設定・取得するために重要です。
 */
function demonstrateMbInternalEncodingUsage(): void
{
    echo "--- 現在の内部エンコーディングを取得 ---\n";
    // 引数なし、またはnullを指定した場合、現在の内部エンコーディング名（文字列）を返します。
    $currentEncoding = mb_internal_encoding();
    echo "現在のエンコーディング: " . $currentEncoding . "\n\n";

    echo "--- 新しい内部エンコーディングを設定 ---\n";
    $newEncoding = 'UTF-8'; // ウェブアプリケーションで一般的に使われるエンコーディング
    // エンコーディングを設定します。成功すればtrue、失敗すればfalseを返します。
    if (mb_internal_encoding($newEncoding)) {
        echo "エンコーディングを '" . $newEncoding . "' に設定しました。\n";
    } else {
        echo "エンコーディングを '" . $newEncoding . "' に設定できませんでした。\n";
        // 無効なエンコーディング名を指定した場合などに失敗することがあります。
    }

    // 変更が反映されたか確認します。
    echo "確認のための現在のエンコーディング: " . mb_internal_encoding() . "\n\n";

    echo "--- 無効なエンコーディング名での設定を試行 ---\n";
    $invalidEncoding = 'INVALID-ENCODING-NAME'; // 存在しないエンコーディング名を指定
    if (mb_internal_encoding($invalidEncoding)) {
        echo "予期せずエンコーディングを '" . $invalidEncoding . "' に設定しました。\n";
    } else {
        echo "エンコーディングを '" . $invalidEncoding . "' に設定できませんでした (正しい挙動)。\n";
    }
    // 無効な試行後もエンコーディングは変更されていないことを確認します。
    echo "無効な試行後の現在のエンコーディング: " . mb_internal_encoding() . "\n";
}

// 関数を実行してデモンストレーションを開始します。
demonstrateMbInternalEncodingUsage();

mb_internal_encoding関数は、PHPが日本語のようなマルチバイト文字を扱う際の、内部的なデフォルト文字エンコーディングを設定、または取得するために使用します。文字化けを防ぐために重要な関数です。

この関数は、引数の有無によって動作が変わります。引数を何も指定せずに呼び出すと、現在設定されている内部エンコーディングの名前を文字列として返します。例えば、'UTF-8'のような値が取得できます。

一方、引数に'UTF-8'や'SJIS-win'といった有効なエンコーディング名を文字列で指定すると、内部エンコーディングをその値に設定します。この場合、設定が成功すれば戻り値としてtrueが、存在しないエンコーディング名を指定するなどして失敗した場合はfalseが返されます。

サンプルコードでは、まず現在のエンコーディングを取得し、次に'UTF-8'に設定しています。最後に、無効なエンコーディング名で設定を試みて失敗する様子も示しており、関数の挙動を具体的に確認できます。

なお、この関数を使おうとして"undefined function"というエラーが表示される場合は、PHPのmbstring拡張モジュールが有効になっていないことが原因です。php.iniファイルの設定を確認してください。