| 1 | # Laravel — фундаментальный слой (framework на PHP) |
| 2 | |
| 3 | **Назначение:** опорная карта **Laravel** как full-stack PHP-фреймворка (HTTP, консоль, очереди, ORM) в связке с **PHP 8.2+** (для Laravel 12 — диапазон **8.2–8.5** по документации laravel.com/docs/12.x). Слой **L1 world** (миру `software.laravel` / `software.web-backend`). Рантайм PHP без фреймворка — в `kb-php-fundamentals-v1.md`. |
| 4 | |
| 5 | **Расширенный контур Laravel (версии, пакеты, безопасность, Symfony, Octane/Reverb, Livewire/Filament/Inertia):** карта и порядок — `index-knowledge-laravel-cluster-v1.md` и kb из той карты; этот файл — **шаг 1** полного Laravel pass. |
| 6 | |
| 7 | **Порядок загрузки:** `status-php-laravel-v1.md` → `playbook-php-v1.md` (при сомнениях по PHP/Composer) → `playbook-laravel-v1.md` → этот файл. |
| 8 | |
| 9 | --- |
| 10 | |
| 11 | ### 1. Место Laravel в стеке |
| 12 | |
| 13 | - **Fact:** Laravel задаёт структуру приложения (контейнер IoC, конфиг, провайдеры), маршрутизацию, слой HTTP, абстракции к БД (**Eloquent**), очереди, события, расписание (**Scheduler**), CLI (**Artisan**). Версия фреймворка и требования к PHP задаются в `composer.json` проекта и документации релиза. |
| 14 | - **Heuristic:** не обсуждать «Laravel» без указания **мажорной версии** приложения (10/11/12) и фактической версии PHP; поведение и API различаются между мажорами. |
| 15 | - **First adoption task:** в README сервиса: Laravel X.Y, PHP A.B, способ деплоя (octane / fpm / horizon). |
| 16 | - **Success criterion:** новый участник понимает контур приложения за один проход по README + `routes/`. |
| 17 | - **Confidence:** high |
| 18 | |
| 19 | --- |
| 20 | |
| 21 | ### 2. Жизненный цикл запроса и границы слоёв |
| 22 | |
| 23 | - **Fact:** HTTP-запрос проходит **middleware**, попадает в **router** → контроллер / closure / invokable; ответ формируется через response; исключения могут маппиться в HTTP через handler. Консольные команды идут через **Artisan** с отдельным bootstrap. |
| 24 | - **Heuristic:** бизнес-правила не смешивать с middleware «толстыми» порциями; тяжёлую работу выносить в jobs/queue. |
| 25 | - **First adoption task:** для каждого нового маршрута определить: auth? validation? rate limit? idempotency? |
| 26 | - **Success criterion:** предсказуемая цепочка middleware; тестируемые контроллеры/действия. |
| 27 | - **Confidence:** high |
| 28 | |
| 29 | --- |
| 30 | |
| 31 | ### 3. Данные: Eloquent, миграции, транзакции |
| 32 | |
| 33 | - **Fact:** **Eloquent** — ORM с моделями, отношениями, scope’ами; **миграции** версионируют схему; **фабрики/сидеры** — для dev/test. Транзакции через `DB::transaction`. |
| 34 | - **Heuristic:** N+1 запросы — первая гипотеза при «медленных страницах»; использовать eager loading осознанно; индексы — на уровне миграций, а не только «в голове». |
| 35 | - **First adoption task:** включить в CI минимальный набор тестов, затрагивающих критичные запросы (или Laravel Pint + статические проверки + ручной профайлинг на стейдже). |
| 36 | - **Success criterion:** нет необъяснимого роста числа запросов на типовой экран. |
| 37 | - **Confidence:** medium |
| 38 | |
| 39 | --- |
| 40 | |
| 41 | ### 4. Конфигурация, окружение, кеш |
| 42 | |
| 43 | - **Fact:** `.env` задаёт секреты и среду; `config/*` — кешируемые значения; `php artisan config:cache`, `route:cache`, `view:cache` используются в проде для производительности; после смены env нужен redeploy/clear кеша. |
| 44 | - **Heuristic:** **никогда** не коммитить `.env` с секретами; в проде не полагаться на «забытый» `config:cache` от старой схемы. |
| 45 | - **First adoption task:** документировать обязательные переменные окружения (таблица имя / назначение / пример без секрета). |
| 46 | - **Success criterion:** поднятие нового окружения по чек-листу env без угадывания. |
| 47 | - **Confidence:** high |
| 48 | |
| 49 | --- |
| 50 | |
| 51 | ### 5. Очереди, фоновые задачи, расписание |
| 52 | |
| 53 | - **Fact:** **Queue** worker обрабатывает jobs; **Horizon** (опционально) даёт UI и метрики для Redis-очередей; **Scheduler** требует cron entry `schedule:run` каждую минуту. |
| 54 | - **Heuristic:** долгие HTTP-запросы — кандидаты в job; идемпотентность и retry policy описывать явно. |
| 55 | - **First adoption task:** для каждого job: timeout, tries, backoff, failed handler. |
| 56 | - **Success criterion:** нет «потерянных» задач без мониторинга failed_jobs / алертов. |
| 57 | - **Confidence:** medium |
| 58 | |
| 59 | --- |
| 60 | |
| 61 | ### 6. Тестирование и качество |
| 62 | |
| 63 | - **Fact:** стандартный стек: **PHPUnit** или **Pest**; HTTP-тесты через `get/post` helpers; фабрики моделей; параллельный прогон в CI. |
| 64 | - **Heuristic:** критичные use-case покрыть интеграционными тестами с реальной БД (test sqlite/mysql) важнее, чем 100% покрытие утилит. |
| 65 | - **First adoption task:** минимальный smoke suite на deploy; статанализ (PHPStan/Larastan) по мере зрелости. |
| 66 | - **Success criterion:** регрессии ловятся до продакшена. |
| 67 | - **Confidence:** medium |
| 68 | |
| 69 | --- |
| 70 | |
| 71 | ## Registry card (template-knowledge-card-v1) |
| 72 | |
| 73 | ### Provenance (происхождение) |
| 74 | - source_refs: `https://laravel.com/docs/12.x/releases` (требования PHP); обобщение архитектуры Laravel из официальной документации; связка с кластером Laravel 2026-03-01. |
| 75 | - created_at: 2026-02-28 |
| 76 | - updated_at: 2026-03-01 |
| 77 | - author: agent-notes KB maintainer |
| 78 | |
| 79 | ### Metadata |
| 80 | - card_id: KC-2026-02-28-LARAVEL-L1 |
| 81 | - world: software.laravel |
| 82 | - layer: world |
| 83 | - tags: laravel; php; eloquent; queue; artisan; http; cluster-entry |
| 84 | - status: active |
| 85 | |
| 86 | ### Epistemic Linkage |
| 87 | - epistemic_basis: fact + inference |
| 88 | - evidence_type: official Laravel docs + общеотраслевые практики |
| 89 | - confidence: medium |
| 90 | - uncertainty: детали конкретного мажора (10 vs 11 vs 12) — всегда сверять с docs выбранной ветки |
| 91 | - falsification_trigger: несовпадение с документацией для заявленной версии Laravel |
| 92 | - transfer_boundary: не переносить соглашения одного мажора на другой без чтения upgrade guide |
| 93 | |
| 94 | ### Core Unit |
| 95 | - context: проектирование фич, отладка Laravel, деплой, очереди |
| 96 | - signal: «где разместить логику», «почему 500», «как кешировать», «как тестировать» |
| 97 | - action: playbook-laravel-v1 → точечный kb; версии из composer.lock |
| 98 | - outcome: решения в рамках идиоматичного Laravel |
| 99 | - lesson: Laravel силён соглашениями — сначала конвенции, потом кастом |
| 100 | |
| 101 | ### Operationalization |
| 102 | - first_adoption_task: задокументировать версии и обязательные env; настроить CI |
| 103 | - validation_check: `php artisan test`, smoke после `config:cache` |
| 104 | - success_criterion: стабильный деплой и наблюдаемость очередей |
| 105 | - rollback_or_mitigation: откат релиза + очистка кеша конфигов |
| 106 | |
| 107 | ### Lifecycle |
| 108 | - supersedes: — |
| 109 | - superseded_by: — |
| 110 | - deprecation_reason: — |
| 111 | |