Laravel и PHP с Codex

Проверено: 20 июля 2026 года.

Сначала определить фактическую версию PHP, Laravel и пакетов по composer.json и lock-файлу. Документация 13.x ниже актуальна на дату проверки, но проектная версия всегда важнее.

Перед изменением

• Прочитать проектные AGENTS.md, README, composer.json, test config и контейнерные инструкции.
• Найти аналогичные route/controller/action/model/job/test в проекте.
• Проверить auth middleware, policies, validation, casts, events и транзакции.
• Выполнять PHP, Composer и Artisan штатным способом проекта, обычно внутри его контейнера.
• Для незнакомого API открыть документацию именно установленной версии.

Laravel Boost может предоставить Codex version-aware документацию, guidelines и MCP-инструменты. Подключать его только по правилам проекта после проверки пакета и разрешений; наличие Boost не заменяет чтение кода и тесты. См. Laravel Boost и Laravel AI.

Архитектура и код

• Следовать уже принятой организации приложения; не вводить новый service/ repository/action слой только по универсальному шаблону.
• Controllers и console commands держать оркестрационными, предметные инварианты — в подходящем слое проекта.
• Request validation и authorization проверять отдельно: валидный ввод ещё не означает разрешённое действие.
• Для массового присваивания явно учитывать $fillable/$guarded и casts.
• Eloquent-запросы проверять на N+1, объём выборки, индексы и eager loading.
• Для больших наборов использовать pagination/chunk/cursor по требованиям консистентности, а не загружать всё в память.
• Транзакции ограничивать минимальным атомарным участком; внешние вызовы не удерживать внутри долгой транзакции без необходимости.

Миграции и данные

• Схему менять только миграциями.
• Не использовать migrate:fresh, wipe, DROP или TRUNCATE на реальных данных без прямого подтверждения и датированной резервной копии.
• Для production учитывать rolling deployment: старая и новая версия приложения могут работать одновременно.
• Разделять добавление nullable/backfilled поля, заполнение данных и ужесточение ограничения, если единая миграция опасна.
• Проверять обратимость; если автоматический down() небезопасен, документировать реальный rollback.
• Никогда не использовать production БД в автоматических тестах.

Очереди, события и scheduler

• Job должен быть идемпотентным либо защищён от опасного повторного выполнения.
• Настроить разумные timeout, retry/backoff и обработку failed jobs.
• Не передавать лишние или чувствительные данные в сериализованную job.
• После commit отправлять работу, которая не должна увидеть незавершённую транзакцию.
• Для scheduler учитывать overlap, timezone, один экземпляр и поведение при пропущенном запуске.

Официальные разделы: Queues и Task Scheduling.

Проверки

Минимальный применимый набор:

1. Целевой PHPUnit/Pest-тест.
2. Feature-тест для HTTP, middleware, validation, DB и serialization.
3. Unit-тест для чистой предметной логики, если он действительно изолирован.
4. Laravel Pint в режиме проекта.
5. PHPStan/Larastan на принятом уровне.
6. Связанные тесты пакета и ручной smoke-check критического сценария.

Не заменять feature-тест моками там, где дефект связан с framework lifecycle, SQL, container binding, queue serialization или middleware.

Ссылки: Testing, Pint, Larastan, PHP-FIG PSR.

Для наблюдаемой отладки сначала проверить уже принятые в проекте Telescope, Horizon, Pulse, Dusk или Pest Browser. Не устанавливать все системы одновременно: матрица назначения и правила безопасного применения находятся в DEBUGGING.md. Выбор first-party или стороннего package проверять по REUSE.md.

Deployment

Codex не должен самостоятельно деплоить, очищать production cache или перезапускать workers без прямой просьбы. Перед выпуском проверить миграции, config/route/view cache, queue workers, health endpoint, логи и rollback по runbook проекта. Отправная точка — Laravel Deployment.