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

<?php

/**
 * spl_autoload_register を使用して複数のディレクトリからクラスを自動ロードする例。
 *
 * このコードを実行するには、以下のディレクトリとファイルを作成してください。
 * (index.php を保存したディレクトリをルートとします)
 *
 * .
 * ├── index.php      (このコードを保存するファイル)
 * ├── lib/
 * │   └── Logger.php
 * └── models/
 *     └── User.php
 *
 *
 * ◆ lib/Logger.php の内容:
 * <?php
 * class Logger
 * {
 *     public function log(string $message): void
 *     {
 *         echo "[LOG] " . $message . PHP_EOL;
 *     }
 * }
 *
 * ◆ models/User.php の内容:
 * <?php
 * class User
 * {
 *     public function getName(): string
 *     {
 *         return "John Doe";
 *     }
 * }
 */

// オートロード対象の基底ディレクトリのリストを定義します。
// spl_autoload_register に登録されるコールバック関数は、これらのディレクトリを順番に検索します。
$autoloadDirectories = [
    __DIR__ . '/lib/',    // 'lib' ディレクトリを検索対象に追加
    __DIR__ . '/models/', // 'models' ディレクトリを検索対象に追加
    // 必要に応じて、他のディレクトリもここに追加できます。
    // 例: __DIR__ . '/src/utility/',
];

/**
 * spl_autoload_register にコールバック関数を登録します。
 * この関数は、プログラム中でまだ定義されていないクラスが初めて使われたときに自動的に呼び出されます。
 *
 * @param string $className 存在しないクラスの名前 (例: 'Logger', 'User')
 * @return void
 *
 * ※ spl_autoload_register の第2引数 ($throw) はデフォルトで true (オートロード失敗時に Throwable をスロー)、
 *    第3引数 ($prepend) はデフォルトで false なので、ここでは省略しています。
 */
spl_autoload_register(function (string $className) use ($autoloadDirectories): void {
    // クラス名からファイル名を推測します (例: 'Logger' -> 'Logger.php')。
    $fileName = $className . '.php';

    // 登録された各ディレクトリを順番に検索します。
    foreach ($autoloadDirectories as $directory) {
        $filePath = $directory . $fileName;

        // 指定されたパスにファイルが存在するか確認し、存在すればそのファイルを読み込みます。
        if (file_exists($filePath)) {
            require_once $filePath;
            // クラスが見つかり、読み込みが成功したらこのオートローダの処理を終了します。
            // これにより、他のオートローダが不必要に実行されるのを防ぎます。
            return;
        }
    }

    // ここに到達した場合、どの登録ディレクトリでもクラスファイルが見つからなかったことを意味します。
    // spl_autoload_register のデフォルト設定により、PHPは未定義クラスのFatal Errorを発生させます。
    // 必要であれば、ここでカスタムのエラーログ出力などの処理を追加することも可能です。
});


// --- オートロードされたクラスの利用例 ---

echo "--- オートロードのテストを開始します ---" . PHP_EOL;

// Logger クラスは 'lib/Logger.php' から自動的にロードされます。
if (class_exists('Logger')) {
    $logger = new Logger();
    $logger->log("アプリケーションが起動しました。");
} else {
    echo "エラー: 'Logger' クラスが見つかりませんでした。'lib/Logger.php' ファイルが存在するか確認してください。" . PHP_EOL;
}

echo PHP_EOL;

// User クラスは 'models/User.php' から自動的にロードされます。
if (class_exists('User')) {
    $user = new User();
    echo "ユーザー名: " . $user->getName() . PHP_EOL;
} else {
    echo "エラー: 'User' クラスが見つかりませんでした。'models/User.php' ファイルが存在するか確認してください。" . PHP_EOL;
}

echo PHP_EOL;

// 存在しないクラスを試した場合。
// オートロードに失敗し、`spl_autoload_register`のデフォルト設定（第2引数 $throw が true）により
// `Throwable` (PHP 7 以降の基底エラーインターフェース) がスローされます。
try {
    echo "存在しないクラス 'NonExistentClass' を試します..." . PHP_EOL;
    $nonExistent = new NonExistentClass();
} catch (Throwable $e) {
    echo "Caught Error: 未定義クラス 'NonExistentClass' の使用: " . $e->getMessage() . PHP_EOL;
}

echo PHP_EOL;
echo "--- オートロードのテストが完了しました ---" . PHP_EOL;

spl_autoload_registerは、PHPで未定義のクラスがプログラム中で初めて使用された際に、そのクラス定義ファイルがどこにあるかを自動的に探し、読み込むための関数です。これにより、プログラムの冒頭で大量のrequire文を書く手間を省き、コードの見通しを良くできます。

この関数には、クラス名を受け取り、クラス定義ファイルを探してrequire_onceで読み込む処理を記述したコールバック関数（$callback）を登録します。サンプルコードでは、複数の検索対象ディレクトリを定義し、その中からクラス名に対応するファイルを探し出して読み込むカスタムオートローダーを登録しています。

第2引数$throwはオートロードに失敗した場合にThrowableをスローするかどうか（デフォルトはtrue）、第3引数$prependは登録するオートローダーを既存のリストの先頭に追加するかどうか（デフォルトはfalse）を制御します。関数は登録に成功した場合true、失敗した場合falseを返します。

このようにspl_autoload_registerを利用することで、例えばlib/Logger.phpやmodels/User.phpのような異なるディレクトリに分散したクラスファイルを、new Logger()やnew User()と記述するだけで自動的に読み込めるようになり、大規模なアプリケーションのファイル管理を効率化できます。未定義クラスが見つからない場合は、デフォルトでエラーが発生します。

<?php

/**
 * spl_autoload_register の使用例
 *
 * このスクリプトは、`spl_autoload_register` を使って、
 * 定義されていないクラスが使われたときに自動的にそのクラスファイルを読み込む方法を示します。
 * また、「spl_autoload_register not working」という一般的な問題がなぜ発生するか、
 * そしてそれをどのように特定できるかについても示唆します。
 */

// クラスファイルが配置される基準ディレクトリを定義します。
// この例では、`index.php` と同じ階層に `src/` ディレクトリがあると仮定しています。
// 例:
// your_project/
// ├── index.php
// └── src/
//     └── MyClass.php
const BASE_DIR = __DIR__ . '/src/';

/**
 * カスタムオートロード関数を登録します。
 *
 * この関数は、PHPがまだ定義されていないクラス（例: `new MyClass()`）を使おうとしたときに、
 * 自動的に呼び出されます。その目的は、クラスが定義されているファイルを特定して読み込むことです。
 *
 * @param string $className ロードするクラスの完全修飾名 (例: 'MyClass' または 'App\Namespace\ClassName')。
 * @return void
 */
spl_autoload_register(function (string $className): void {
    // クラス名をファイルパスに変換します。
    // 名前空間の区切り文字 ('\') をディレクトリの区切り文字 ('/') に置換します。
    // '.php' 拡張子を追加します。
    // 例: 'MyClass' -> 'MyClass.php'
    // 例: 'App\Utils\Helper' -> 'App/Utils/Helper.php'
    $filePath = BASE_DIR . str_replace('\\', DIRECTORY_SEPARATOR, $className) . '.php';

    // 構築されたパスにファイルが存在するかどうかを確認します。
    if (file_exists($filePath)) {
        require_once $filePath;
        echo "オートロード成功: " . $filePath . "\n";
    } else {
        // ファイルが存在しない場合、このクラスのオートロードは「失敗」します。
        // これは、ファイルパスが正しくないか、ファイル自体が見つからない場合に
        // 「spl_autoload_register not working」が発生する一般的な原因です。
        error_log("クラス '{$className}' のオートロードに失敗しました。ファイルが '{$filePath}' に見つかりません。");
        // $throw が true (デフォルト) の場合、PHPは通常、致命的なエラー (Class not found) をスローします。
    }
}, true, true); // 2番目の 'true' は $throw (見つからない場合に例外をスローするかどうか)、
              // 3番目の 'true' は $prepend (オートローダーをスタックの先頭に追加するかどうか) です。

// --- この例を単体で動作可能にするため、ダミークラスファイルの内容を作成します ---
// 実際のシナリオでは、'src/MyClass.php' は独立したファイルとして存在します。
$myClassContent = <<<'PHP_CLASS'
<?php
class MyClass
{
    public function __construct()
    {
        echo "MyClass のインスタンスが作成されました。\n";
    }

    public function getMessage(): string
    {
        return "これはオートロードされた MyClass からのメッセージです。";
    }
}
PHP_CLASS;

// `src` ディレクトリが存在しない場合は作成します
if (!is_dir(BASE_DIR)) {
    mkdir(BASE_DIR, 0777, true);
}

// デモンストレーション用にダミークラスファイルを作成します。
// 実際のアプリケーションでは、このファイルはプロジェクト構造の一部として存在します。
$classFilePath = BASE_DIR . 'MyClass.php';
if (!file_exists($classFilePath)) {
    file_put_contents($classFilePath, $myClassContent);
    echo "ダミーファイルを作成しました: " . $classFilePath . "\n";
}

echo "\n--- クラスのオートロードを実演します ---\n";

// PHP は MyClass のインスタンスを作成しようとします。
// MyClass がまだ定義されていないため、`spl_autoload_register` に登録されたコールバックが呼び出されます。
try {
    $myObject = new MyClass();
    echo $myObject->getMessage() . "\n";
} catch (Throwable $e) {
    echo "エラーが発生しました: " . $e->getMessage() . "\n";
}

echo "\n--- オートロードの失敗を実演します (意図的) ---\n";

// 次に、存在しないクラスをロードしようとすることで、「not working」のシナリオをシミュレートします。
try {
    echo "NonExistentClass のインスタンス化を試みます...\n";
    // このクラスは存在しないため、オートローダーはファイルを読み込めず、
    // 致命的なエラー (Class not found) が発生するはずです。
    $nonExistentObject = new NonExistentClass();
    echo "NonExistentClass が正常にインスタンス化されました (予期せぬ動作)。\n";
} catch (Throwable $e) {
    echo "予期されたエラーをキャッチしました: " . $e->getMessage() . "\n";
    echo "これは、オートローダーが 'NonExistentClass' を見つけられなかったことを示しており、\n";
    echo "\$throw が true の場合に致命的なエラーにつながります。\n";
}

// デモンストレーション後にダミーファイルをクリーンアップしたい場合 (オプション)
// unlink($classFilePath);
// rmdir(BASE_DIR); // ディレクトリ内に他のファイルがあると失敗する可能性があります

echo "\nオートロードのデモンストレーションが完了しました。\n";

spl_autoload_registerは、PHPで未定義のクラスが使われた際に、自動的にそのクラスファイルを読み込むための関数です。手動でのrequire文を減らし、コードの保守性を高めます。

第一引数$callbackには、クラス名を受け取り、そのクラスファイルを読み込む処理を記述した関数を指定します。クラス名を基にファイルパスを生成し、require_onceなどで読み込みます。

第二引数$throwはオートロード失敗時にPHPが例外をスローするか（デフォルトtrue）、第三引数$prependは既存リストの先頭に追加するか（デフォルトfalse）を真偽値で指定します。戻り値は登録の成否を表すboolです。

サンプルコードは、カスタムオートロード関数を登録し、MyClassのインスタンス化時にsrc/MyClass.phpが自動的に読み込まれる例です。「spl_autoload_register not working」という問題は、オートロード関数がクラスファイルを正しく見つけられない場合に発生します。ファイルパスの誤りやファイルの不在が原因で、$throwがtrueであればエラーとして顕在化し、問題特定に役立ちます。