PHP Fatal error: Uncaught Error: Class ‘X’ not found の原因と解決方法【名前空間とオートロードの完全理解】

Fatal error: Uncaught Error: Class ‘X’ not found とは

PHP開発で頻繁に遭遇する「Fatal error: Uncaught Error: Class ‘X’ not found」は、指定されたクラスが見つからない場合に発生する致命的なエラーです。これは、クラスファイルの読み込みに失敗しているか、名前空間の指定が間違っていることを意味します。特にComposerを使った現代的なPHP開発において、オートロードの仕組みと名前空間の理解が解決の鍵となります。

デプロイ太郎

このエラー、特にプロジェクトに新しく参加した時や、既存のコードベースを触り始めた時に出やすいですよね。Composerのautoload周りが原因のことが多いです。

実行環境ごとのエラーメッセージ

エラーの発生パターン

このエラーは主に以下のようなケースで発生します。

パターン1: パターン1: 名前空間のuseステートメントの欠落または誤り

```php
// src/Service/UserService.php
namespace App\Service;

class UserService
{
    public function getUser() { /* ... */ }
}

// public/index.php
// use App\Service\UserService; // この行がコメントアウトされている、または存在しない

$userService = new UserService(); // Fatal error: Uncaught Error: Class 'UserService' not found
$userService->getUser();
```

名前空間を使用しているクラスを呼び出す際、そのクラスの完全修飾名（FQCN）を使用しない場合、useステートメントでエイリアスを定義する必要があります。useステートメントがないか、または間違っていると、PHPはグローバル名前空間でクラスを探し、見つからないためにエラーとなります。

```php
// public/index.php
use App\Service\UserService; // 正しいuseステートメントを追加

$userService = new UserService();
$userService->getUser();
```

パターン2: パターン2: オートローダーの設定ミスまたは更新忘れ (Composer)

```php
// composer.json にPSR-4オートロード設定がある
// {
//   "autoload": {
//     "psr-4": {
//       "App\\": "src/"
//     }
//   }
// }

// src/Model/Product.php を新規作成
namespace App\Model;

class Product
{
    public function getName() { return 'New Product'; }
}

// public/index.php
require __DIR__ . '/../vendor/autoload.php';

use App\Model\Product;

$product = new Product(); // Fatal error: Uncaught Error: Class 'App\Model\Product' not found
// 新しいクラスファイルを追加した後に `composer dump-autoload` を実行し忘れている
```

Composerなどのオートローダーを使用している場合、新しいクラスファイルを追加したり、名前空間やディレクトリ構造を変更したりした際に、オートローダーのインデックスを更新するコマンド（例: composer dump-autoload）を実行し忘れると、クラスが見つからなくなります。

```php
// コマンドラインでオートローダーを更新
// composer dump-autoload

// public/index.php (変更なしで動作するようになる)
require __DIR__ . '/../vendor/autoload.php';

use App\Model\Product;

$product = new Product();
echo $product->getName(); // "New Product"が出力される
```

パターン3: パターン3: クラスファイルのパスやファイル名の誤り (大文字小文字の区別)

```php
// src/Utility/helper.php (ファイル名が小文字)
namespace App\Utility;

class Helper
{
    public function someMethod() { /* ... */ }
}

// public/index.php
require __DIR__ . '/../vendor/autoload.php';

use App\Utility\Helper; // クラス名はHelperだが、オートローダーがファイル名としてhelper.phpを探す

$helper = new Helper(); // Fatal error: Uncaught Error: Class 'App\Utility\Helper' not found (Linux環境など)
```

特にLinux環境などファイルシステムが大文字小文字を区別するOSでは、クラス名とファイル名が一致しない場合にオートローダーがクラスファイルを見つけられないことがあります。通常、PSR-4などの規約ではクラス名とファイル名（拡張子を除く）は完全に一致させるべきです。

```php
// src/Utility/Helper.php (ファイル名をクラス名と一致させる)
namespace App\Utility;

class Helper
{
    public function someMethod() { /* ... */ }
}

// public/index.php (変更なしで動作するようになる)
require __DIR__ . '/../vendor/autoload.php';

use App\Utility\Helper;

$helper = new Helper();
$helper->someMethod();
```

デプロイ太郎

「あれ？クラス名合ってるはずなのに…」ってなった時、useの有無か、composer dump-autoloadの実行忘れ、あとは地味にファイル名の大文字小文字ミスが多い印象ですね。

よくあるバリエーション

Class 'App\Http\Controllers\MyClass' not found の場合

Laravelでこのエラーが出る場合、コントローラーの名前空間内に存在しないクラスを呼び出している可能性が高いです。多くは、App\Http\Controllers以外の名前空間にあるクラス（例: App\Services\MyService）を呼び出す際に、use App\Services\MyService;のようなuseステートメントを書き忘れていることが原因です。

```php
// Bad (Laravel Controller)
namespace App\Http\Controllers;

class MyController extends Controller
{
    public function index()
    {
        $service = new MyService(); // ここでエラー
    }
}

// Good (Laravel Controller)
namespace App\Http\Controllers;

use App\Services\MyService; // MyServiceの正しい名前空間をuse

class MyController extends Controller
{
    public function index()
    {
        $service = new MyService();
    }
}
```

Class 'GuzzleHttp\Client' not found の場合

これはComposerでインストールした外部ライブラリのクラスが見つからない場合に非常によく見られます。原因はcomposer installまたはcomposer updateの実行忘れ、あるいはvendor/autoload.phpの読み込み忘れがほとんどです。特に、開発環境で動作しても本番環境でエラーになる場合は、vendorディレクトリがデプロイされていない可能性もあります。

```php
// Bad
// composer.json に "guzzlehttp/guzzle": "^7.0" があるが、
// `composer install` を実行していない、または vendor/autoload.php を読み込んでいない
// use GuzzleHttp\Client;
// $client = new Client(); // エラー

// Good
// 1. `composer install` を実行
// 2. コードの先頭で require __DIR__ . '/vendor/autoload.php'; を記述
require __DIR__ . '/vendor/autoload.php';

use GuzzleHttp\Client;
$client = new Client(); // 成功
```

フレームワーク別の発生パターン

Laravelでの発生パターン

Laravelでは、appディレクトリ以下のクラスは自動的にオートロードされますが、それ以外のカスタムディレクトリにクラスを作成した場合や、サービスプロバイダで正しく登録されていない場合にClass 'X' not foundエラーが発生することがあります。特にapp/Http/Controllers外のヘルパークラスやリポジトリクラスでよく見られます。

```php
// Bad Code (Laravel)
// app/Services/MyService.php を作成したが、composer.jsonに追記し忘れ
// public function index(Request $request)
// {
//     $service = new MyService(); // Class 'App\Http\Controllers\MyService' not found (App\Services\MyService ではなくコントローラーの名前空間で探してしまう)
//     return $service->doSomething();
// }

// Good Code (Laravel)
// app/Services/MyService.php
namespace App\Services;

class MyService { /* ... */ }

// app/Http/Controllers/ExampleController.php
namespace App\Http\Controllers;

use App\Services\MyService; // 正しいuseステートメントを追記

class ExampleController extends Controller
{
    public function index(Request $request)
    {
        $service = new MyService(); // 解決される
        return $service->doSomething();
    }
}
// また、composer.jsonのpsr-4設定を確認し、必要なら `composer dump-autoload` を実行
```

Symfonyでの発生パターン

Symfonyアプリケーションで新しいバンドルやサービスを作成した際、Composerのオートローダー設定が正しくない、または更新されていない場合にこのエラーが発生します。特に既存のcomposer.jsonにない名前空間でクラスを定義した場合や、外部ライブラリを追加した後にcomposer install/updateを忘れた場合に注意が必要です。

```php
// Bad Code (Symfony)
// src/Service/CustomMailer.php (名前空間 App\Service)
// config/services.yaml に CustomMailer をサービスとして定義したが、
// `composer.json` の `autoload` 設定に `App\` 名前空間が `src/` ディレクトリにマッピングされていない、または `composer dump-autoload` 忘れ

// Good Code (Symfony)
// composer.json
// {
//   "autoload": {
//     "psr-4": {
//       "App\\": "src/"
//     }
//   }
// }
// `composer dump-autoload` を実行

// src/Controller/MailerController.php
namespace App\Controller;

use App\Service\CustomMailer;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;

class MailerController extends AbstractController
{
    public function sendMail(CustomMailer $mailer): Response
    {
        // $mailer はDIコンテナによって自動的に解決される
        $mailer->send();
        return new Response('Email sent!');
    }
}
```

根本原因の特定方法

このエラーが発生したら、まずエラーメッセージに表示されているクラス名と、そのクラスが実際に存在するファイルパス、そして名前空間が一致しているかを確認します。特にComposerを使用している場合は、コマンドラインでcomposer dump-autoloadを実行してオートローダーを再生成し、問題が解決するか試してください。また、var_dump(class_exists('Fully\Qualified\ClassName'));を使って、PHPがそのクラスを認識しているか確認するのも有効です。

```php
// 例えば、App\Service\UserService クラスが見つからない場合
var_dump(class_exists('App\Service\UserService')); // bool(false) が返るはず

// オートローダーが正しく読み込まれているか確認
var_dump(function_exists('spl_autoload_functions'));
if (function_exists('spl_autoload_functions')) {
    var_dump(spl_autoload_functions()); // 登録されているオートローダー関数が表示される
}
```

PHPのオートロードと名前空間の仕組み

PHPのクラスが見つからないエラーは、主にオートロード（自動読み込み）の仕組みと深く関わっています。PHP 5.3以降導入された名前空間（namespace）は、クラス名の衝突を防ぐために使用されます。オートローダーは、new ClassName()が呼ばれたときに、そのクラス定義がどこにあるべきかを推測し、該当するファイルを読み込もうとします。ComposerはPSR-4などの標準に従ってこのオートロードを強力にサポートしており、composer.jsonで定義されたルールに基づいてvendor/autoload.phpを生成します。このファイルが正しくインクルードされていない、またはオートロードキャッシュが古い場合にエラーが発生します。

防止策とベストプラクティス

このエラーを予防するためには、Composerのオートロードを常に最新の状態に保つことが最も重要です。新しいクラスを作成したり、ライブラリを追加したりした際は、必ずcomposer dump-autoloadを実行しましょう。また、IDEのオートコンプリート機能を活用し、useステートメントや完全修飾名を正確に記述することも有効です。ファイル名とクラス名、名前空間の規約（PSR-4など）に厳密に従うことも忘れずに。

```php
// 新しいクラスファイルを作成・変更したら必ず実行
// composer dump-autoload

// IDEの自動補完機能を利用してuseステートメントを正確に記述
use App\Utility\Helper;

// クラス名とファイル名、名前空間の規約を遵守
// src/Service/MyService.php に namespace App\Service; class MyService { ... } と記述
```

よくある質問（FAQ）