# Устранение неполадок Elang Начните с точной команды или URL, которые вызвали сбой. Отметьте HTTP-статус, версию PHP и последнее выполненное действие. Небольшую воспроизводимую проблему легче решить, чем менять сразу несколько настроек. ## PHP или Composer не распознаётся После установки любого из инструментов заново откройте терминал. Выполните `where.exe php` в Windows или `command -v php` в macOS и Linux. Если результат указывает на старую установку, исправьте PATH вместо изменения требований Elang. Выполните `php -v` и `composer --version`. Elang требует PHP 8.3+ в пределах ветки PHP 8.x и Composer 2. Если какая-либо команда недоступна, пройдите [урок по окружению](/learn/environment). ## Composer сообщает об отсутствующем расширении Выполните `php --ini`, чтобы найти конфигурацию CLI, затем `php -m`, чтобы проверить загруженные модули. Включите или установите указанное расширение для той версии PHP, которую действительно использует Composer. Не используйте `--ignore-platform-reqs`, чтобы скрыть проблему. Это может привести к установке, которая завершится ошибкой при выполнении. Установка расширения для PHP-FPM не обязательно включает его для CLI PHP, и наоборот. ## Отсутствует vendor/autoload.php Перейдите в каталог, содержащий `composer.json` вашего приложения, затем выполните: ```bash composer install ``` Дождитесь успешного завершения команды. Каталог `vendor/` создаётся Composer и намеренно исключён из скачиваемого исходного кода и Git-репозитория. ## Ключ приложения отсутствует или недопустим Выполните `php elang key:generate` из каталога приложения. После этого doctor должен сообщить о корректном ключе шифрования. Ключ должен быть 32-байтовым значением в кодировке base64. Храните `.env` в закрытом доступе. Не заменяйте действующий ключ рабочей среды только ради диагностики посторонней ошибки: прежние зашифрованные данные зависят от этого ключа. Генератор отказывается заменять непустой ключ без `--force`. ## Не удаётся подключиться к базе данных Выполните `php elang doctor`. Для SQLite проверьте, что включён `pdo_sqlite` и родительский каталог базы данных доступен для записи. Для MySQL или PostgreSQL проверьте соответствующий драйвер PDO, доступность сервера, имя базы данных и учётные данные. Кодируйте специальные символы в учётных данных подключения в формате URL. Никогда не вставляйте реальный URL подключения в публичную задачу. Doctor скрывает учётные данные в своём выводе. ## Таблица отсутствует или не существует Подключение может работать, даже если схема ещё не создана. Выполните: ```bash php elang migrate:status php elang migrate ``` В рабочей среде проверьте ожидающие файлы миграций и используйте `--force` только после подготовки резервной копии. Если вы изменили DATABASE_URL, теперь вы можете обращаться не к той базе данных, к которой применяли миграции. ## Маршрут возвращает 404 Выполните `php elang routes`. Сравните метод и путь со своим запросом. Требование параметра, например `[0-9]+`, намеренно отклоняет `/posts/hello`. Если `/` работает, а другие страницы на веб-сервере нет, проверьте корневой веб-каталог и правило перенаправления. Apache должен учитывать включённый `.htaccess`; Nginx требуется правило `try_files`, которое достигает `index.php`. 404 означает, что запрошенный ресурс не найден. Не следует исправлять это, превращая все отсутствующие страницы в ответы 200. ## Запрос возвращает 405 Путь существует, но HTTP-метод не совпадает. Форме POST нужен маршрут POST. Проверьте заголовок ответа `Allow` и список маршрутов. Адресная строка браузера отправляет GET, поэтому через неё нельзя напрямую проверить эндпоинт, принимающий только POST. ## Форма возвращает 419 Токен CSRF отсутствует, просрочен или относится к другой сессии. Снова откройте форму и отправьте заново сформированный токен. Убедитесь, что SessionMiddleware выполняется перед CsrfMiddleware, форма содержит `_token`, а браузер принимает cookie сессии. При использовании fetch с cookie между разными источниками важны правила источников и cookie. Во время обучения начните с формы того же источника. CSRF не заменяет вход или авторизацию. ## API возвращает 400, 415 или 422 - **400:** JSON не удалось разобрать, параметр имеет недопустимую форму или структура запроса неверна. - **415:** Эндпоинт ожидает `Content-Type: application/json`. - **422:** Разбор прошёл успешно, но поле не прошло валидацию. Прочитайте объект `errors`, а не угадывайте, какое поле вызвало ошибку. Посмотрите разницу на конкретных запросах в [примере валидации](/examples/validated-api). ## Запрос возвращает 429 Достигнуто ограничение частоты API-запросов. Подождите в течение периода `Retry-After`. Во время тестирования повторные вызовы с одного определённого IP-адреса используют общий счётчик. Обработку клиентского IP за обратным прокси нужно настраивать осознанно; не доверяйте произвольным перенаправленным заголовкам вслепую. ## Страница возвращает 500 Найдите идентификатор запроса в ответе и изучите `storage/logs/app.log` на сервере. Ответы рабочей среды скрывают внутренние сообщения исключений. Рядом с этим идентификатором запроса ищите отсутствующую привязку, переменную шаблона, ошибку подключения или проблему прав доступа к файлу. Воспроизведите проблему локально. Предоставьте минимальный пример и очищенный контекст журнала, а не учётные данные, закрытые данные пользователей или весь файл окружения рабочей среды. ## Изменения не видны Проверьте, что вы изменили обслуживаемое приложение, а не другую рабочую копию. Перезагрузка исходников Twig включена. Официальный сайт версионирует URL CSS и JavaScript по времени изменения файлов. Для собственных ресурсов меняйте версию или имя файла при развёртывании обновлений. Если вы используете PHP OPcache с отключённой проверкой времени изменения, при развёртывании необходимо перезапустить соответствующие процессы PHP. Не сбрасывайте посторонние сервисы вслепую. ## Проблема осталась Прочитайте [урок по отладке](/learn/debugging). Полезное сообщение о проблеме включает ревизию фреймворка, версию PHP, команду или запрос, ожидаемый результат, фактический результат и небольшой пример воспроизведения. [Словарь](/docs/v0.1/glossary) объясняет термины, используемые при обсуждении ошибок.