Class not found PHP: как диагностировать и исправить

Расширенные примеры и подробные сценарии

Ниже приведены примеры с пошаговым разбором типичных ситуаций, приводящих к ошибке class not found.

Пример 1. Настройка PSR-4 с последующей автозагрузкой

Структура проекта:

project/
  composer.json
  src/
    Models/
      User.php
  index.php

Содержимое composer.json:

{
    "autoload": {
        "psr-4": {
            "MyApp\\": "src/"
        }
    }
}

После выполнения composer install или composer dump-autoload генерируется vendor/autoload.php.

Файл src/Models/User.php:

<?php
namespace MyApp\Models;

class User {
    public function getName() {
        return 'User from MyApp';
    }
}

Файл index.php:

<?php
require __DIR__ . '/vendor/autoload.php';

use MyApp\Models\User;

$user = new User();
echo $user->getName();

Результат выполнения:

User from MyApp

Если бы файл назывался user.php (строчная 'u'), на Linux возникла бы ошибка.

Пример 2. Явный require с проверкой существования файла

Иногда нужно временно подгрузить класс без автозагрузки:

$classFile = __DIR__ . '/lib/OldClass.php';
if (file_exists($classFile)) {
    require_once $classFile;
} else {
    throw new \RuntimeException('Class file not found');
}
$obj = new OldClass();

Этот подход не рекомендуется для постоянного использования, но полезен при миграции.

Пример 3. Ошибка из-за неверного пространства имён

Класс определён с неймспейсом App\Services, а в index.php пытаются создать экземпляр без use:

// src/Services/Logger.php
namespace App\Services;

class Logger {
    public function log($msg) { echo $msg; }
}

// index.php
require 'vendor/autoload.php';
$logger = new Logger(); // Ищет \Logger, а не \App\Services\Logger
// -> Fatal error: Class "Logger" not found

Исправление:

use App\Services\Logger;
$logger = new Logger();
// или
$logger = new \App\Services\Logger();

Результат после исправления:

(вывод log без ошибок)

Пример 4. Регистрозависимость на Linux

Предположим, есть файл src/Usercontroller.php с классом UserController:

<?php
namespace App;

class UserController { ... }

Автозагрузка PSR-4 ожидает файл UserController.php (с большой буквы C). Если сервер на Linux, Composer не найдёт файл.

Проверить, какие классы загружены, можно так:

var_dump(get_declared_classes());

Если App\UserController отсутствует в списке, вероятно проблема регистра.

Пример 5. Classmap для проектов без неймспейсов

Старый код с глобальными классами:

// lib/OldLogger.php
class OldLogger {
    public function write() { ... }
}

composer.json:

{
    "autoload": {
        "classmap": ["lib/"]
    }
}

После composer dump-autoload -o Composer просканирует lib/ и добавит все классы в маппинг.

В index.php:

require 'vendor/autoload.php';
$logger = new OldLogger();

Результат - класс загружается без ошибок.

Пример 6. Использование собственного автозагрузчика (spl_autoload_register)

Если сторонние решения не подходят, можно написать свою функцию:

spl_autoload_register(function ($class) {
    $prefix = 'MyApp\\';
    $baseDir = __DIR__ . '/src/';
    
    $len = strlen($prefix);
    if (strncmp($prefix, $class, $len) !== 0) {
        return;
    }
    
    $relativeClass = substr($class, $len);
    $file = $baseDir . str_replace('\\', '/', $relativeClass) . '.php';
    
    if (file_exists($file)) {
        require $file;
    }
});

// Теперь классы MyApp\Controllers\HomeController будут загружаться из src/Controllers/HomeController.php

Этот подход даёт полный контроль, но для стандартных проектов лучше использовать Composer.