PHP автозавантаження: оптимізація Composer autoloader

Як працює автозавантаження PHP

Автозавантажувач PHP автоматично підключає файл класу під час першого звернення до нього. Без автозавантажувача довелося б вручну писати require для кожного файлу. Composer генерує автозавантажувач на основі правил із composer.json.

Типи автозавантаження в Composer

Оптимізація автозавантажувача для production

# Базова оптимізація — генерує classmap для всіх PSR-4 класів
composer dump-autoload --optimize

# З вимкненням dev-залежностей
composer dump-autoload --optimize --no-dev

# APCu кеш (найшвидший)
composer dump-autoload --apcu --optimize --no-dev

APCu autoloader (максимальна швидкість)

APCu кешує результати пошуку класів у пам’яті. Потребує розширення php-apcu:

sudo apt install php8.2-apcu

# У composer.json:
{
    "config": {
        "apcu-autoloader": true
    }
}

Конфігурація autoload у composer.json

{
    "autoload": {
        "psr-4": {
            "App\\": "src/",
            "Tests\\": "tests/"
        },
        "classmap": [
            "database/seeds",
            "database/factories"
        ],
        "files": [
            "src/helpers.php"
        ]
    }
}

Laravel: повна оптимізація для production

# Оптимізувати всі кеші
php artisan optimize

# Що робить optimize:
# php artisan config:cache
# php artisan route:cache
# php artisan view:cache
# composer dump-autoload --optimize

Перевірка автозавантаження

# Переглянути згенерований classmap
cat vendor/composer/autoload_classmap.php | head -20

# Розмір файлів autoloader
du -sh vendor/composer/

Типові помилки автозавантаження

Class not found після деплою

PHP Fatal error:  Uncaught Error: Class "App\\Services\\PaymentService" not found in /var/www/html/public/index.php:12

Файл vendor/composer/autoload_classmap.php — статичний знімок, складений на момент запуску dump-autoload. Якщо після цього додали новий клас, а автозавантажувач не перегенерували, PHP просто не знає про нього. Те саме трапляється, якщо в CI зібрали classmap на одній гілці, а задеплоїли іншу.

Failed opening required vendor/autoload.php

PHP Fatal error:  Uncaught Error: Failed opening required 'vendor/autoload.php' (include_path='.:/usr/share/php') in /var/www/html/public/index.php:3

Папка vendor/ зазвичай не потрапляє в git — якщо на сервері після деплою не виконали composer install, автозавантажувача фізично немає.

Коли classmap-оптимізація не підходить

• Активна розробка з частим додаванням класів: після кожного нового класу потрібно перегенерувати карту — забули, отримаєте «Class not found» рівно як у прикладі вище.
• APCu-кеш живе в пам'яті конкретного воркера: після деплою нової версії коду його потрібно скидати окремо, інакше воркер продовжить шукати старі шляхи до файлів.
• Бібліотеки, що створюють класи динамічно під час виконання (eval, рантайм-class_alias), не завжди потрапляють у classmap коректно — для них лишається звичайний PSR-4 пошук.

Перевірка результату

# Детальний вивід покаже кількість класів у карті
composer dump-autoload --optimize -v
# Generated optimized autoload files containing 4821 classes

# Переконатися, що конкретний клас видно автозавантажувачу
php -r "var_dump(class_exists('App\\Services\\PaymentService'));"

Якщо після встановлення Composer і оптимізації клас усе ще не знаходиться — перевірте, що namespace у коді збігається з ключем psr-4 у composer.json побуквено, включно з регістром: на Linux файлова система чутлива до регістру, на відміну від Windows, де помилка може не проявитися в розробника, але вилізе на проді.

Ключова думка цієї таблиці: чим агресивніша оптимізація автозавантажувача, тим суворіша вимога не забувати перегенерувати його після кожної зміни складу класів — це плата за швидкість.

На практиці команду для деплою варто зафіксувати у скрипті збірки раз і назавжди, а не набирати вручну щоразу — людський фактор тут надійно усувається автоматизацією, а не пам'яттю розробника.

Перевіряйте також опцію optimize-autoloader прямо в секції config файлу composer.json — тоді прапор --optimize застосовується автоматично під час будь-якого запуску composer install, і його не потрібно пам'ятати окремо для кожного оточення.