Устранение неполадок 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. Если какая-либо команда недоступна, пройдите урок по окружению.

Composer сообщает об отсутствующем расширении#

Выполните php --ini, чтобы найти конфигурацию CLI, затем php -m, чтобы проверить загруженные модули. Включите или установите указанное расширение для той версии PHP, которую действительно использует Composer.

Не используйте --ignore-platform-reqs, чтобы скрыть проблему. Это может привести к установке, которая завершится ошибкой при выполнении. Установка расширения для PHP-FPM не обязательно включает его для CLI PHP, и наоборот.

Отсутствует vendor/autoload.php#

Перейдите в каталог, содержащий composer.json вашего приложения, затем выполните:

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 скрывает учётные данные в своём выводе.

Таблица отсутствует или не существует#

Подключение может работать, даже если схема ещё не создана. Выполните:

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, а не угадывайте, какое поле вызвало ошибку.

Посмотрите разницу на конкретных запросах в примере валидации.

Запрос возвращает 429#

Достигнуто ограничение частоты API-запросов. Подождите в течение периода Retry-After. Во время тестирования повторные вызовы с одного определённого IP-адреса используют общий счётчик. Обработку клиентского IP за обратным прокси нужно настраивать осознанно; не доверяйте произвольным перенаправленным заголовкам вслепую.

Страница возвращает 500#

Найдите идентификатор запроса в ответе и изучите storage/logs/app.log на сервере. Ответы рабочей среды скрывают внутренние сообщения исключений. Рядом с этим идентификатором запроса ищите отсутствующую привязку, переменную шаблона, ошибку подключения или проблему прав доступа к файлу.

Воспроизведите проблему локально. Предоставьте минимальный пример и очищенный контекст журнала, а не учётные данные, закрытые данные пользователей или весь файл окружения рабочей среды.

Изменения не видны#

Проверьте, что вы изменили обслуживаемое приложение, а не другую рабочую копию. Перезагрузка исходников Twig включена. Официальный сайт версионирует URL CSS и JavaScript по времени изменения файлов.

Для собственных ресурсов меняйте версию или имя файла при развёртывании обновлений. Если вы используете PHP OPcache с отключённой проверкой времени изменения, при развёртывании необходимо перезапустить соответствующие процессы PHP. Не сбрасывайте посторонние сервисы вслепую.

Проблема осталась#

Прочитайте урок по отладке. Полезное сообщение о проблеме включает ревизию фреймворка, версию PHP, команду или запрос, ожидаемый результат, фактический результат и небольшой пример воспроизведения. Словарь объясняет термины, используемые при обсуждении ошибок.