Документация Laravel на laravel.com обычно единственное, что открывает разработчик в первые полчаса работы над новым проектом, и последнее, куда он заглядывает перед сдачей, когда нужно свериться с сигнатурой метода. За несколько лет работы с бэкендами на Laravel я привык относиться к документации не как к учебнику, а как к справочнику: она хорошо отвечает на вопрос «как называется этот метод и какие у него параметры», но почти не отвечает на вопрос «как спроектировать вот этот конкретный кусок системы». Ниже разберу, как устроена документация Laravel на официальном сайте, как ей пользоваться без лишних телодвижений, и что в ней принципиально не описано.
Структура официальной документации Laravel
Сайт laravel.com/docs делит материал на крупные блоки, и если понимать логику этого деления, искать становится быстрее. Prologue отвечает за release notes и upgrade guide, Getting Started за установку и структуру каталогов, Architecture Concepts объясняет жизненный цикл запроса, сервис-контейнер, сервис-провайдеры и фасады. Дальше идёт The Basics: роутинг, middleware, CSRF, контроллеры, запросы и ответы, Blade, валидация, обработка ошибок и логирование.
Отдельный раздел Digging Deeper собирает всё, что не попало в базу: Artisan, broadcasting, кэш, коллекции, события, файловое хранилище, HTTP-клиент, локализация, почта, уведомления, очереди, планировщик задач. Security покрывает аутентификацию, авторизацию, хэширование и сброс пароля. Database и Eloquent ORM идут отдельными блоками с построителем запросов, миграциями, сидерами и полным описанием связей моделей. Testing объясняет HTTP-тесты, консольные тесты и мокинг.
Ниже по странице список официальных пакетов первого лица: Cashier, Dusk, Fortify, Horizon, Octane, Passport, Pennant, Pint, Sanctum, Scout, Socialite, Telescope и другие. У каждого своя страница документации, отдельная от основного раздела, и это важно держать в голове: обновление фреймворка не гарантирует, что вы автоматически прочитали актуальные страницы всех подключённых пакетов.
Версии в документации Laravel и почему это не мелочь
В верхней части каждой страницы docs есть переключатель версий. Это не декоративный элемент: поведение метода, набор параметров или даже само существование фичи может отличаться между релизами. Гуглить ошибку и открывать первую ссылку, не проверив, к какой версии она относится, обычная причина потерянного часа.
Перед тем как читать конкретную страницу, я смотрю версию Laravel в composer.json проекта или запускаю php artisan --version, а потом переключаю документацию на этот же релиз. Если проект переезжает на новую мажорную версию, отдельно открываю страницу Upgrade Guide, там перечислены breaking changes, но без объяснения, зачем команда Laravel решила поменять именно так, только сухой технический список «было, стало».
Как я работаю с документацией Laravel на практике
Со временем вырабатывается привычка не читать документацию подряд, а идти по ней целенаправленно. Пара приёмов, которые экономят время:
- Поиск по странице (Ctrl+F) вместо пролистывания: страницы вроде Validation или Eloquent Relationships длинные, и нужный метод проще найти по названию
php artisan listиphp artisan route:listпоказывают реальное состояние проекта, когда пример из документации не совпадает с тем, что происходит в кодеphp artisan tinkerдля быстрой проверки метода на живых данных, не дожидаясь, пока напишется тест- Переход в исходники класса через IDE, когда пример в доках не покрывает нужный сценарий, у Eloquent и Illuminate\Support достаточно читаемый код с комментариями
- Просмотр самого конфига (
config/queue.php,config/session.phpи так далее), потому что дефолтные значения в конфиге иногда отличаются от значения в примере из документации
Бесплатный материал
🎁 Полезный скрипт в подарок
Подпишитесь на Telegram - пришлю готовый скрипт по этой теме.
Без спама. Отписка в 1 клик.
Что в документации Laravel закрыто действительно хорошо
Есть разделы, где документация Laravel отработана до мелочей. Eloquent Relationships описывает все типы связей, hasOne, hasMany, belongsTo, belongsToMany, hasManyThrough, полиморфные связи, с рабочими примерами кода под каждый случай. Страница Validation перечисляет все правила валидации с параметрами и примерами сообщений об ошибках. Blade Templates подробно разбирает директивы, компоненты, слоты и наследование шаблонов. Queues на базовом уровне тоже покрыты хорошо: как поставить задачу в очередь, как её обработать, как настроить retry и backoff.
Это как раз тот случай, когда справочник работает как справочник: открыл нужную страницу, скопировал сигнатуру метода, применил в своём коде, и в девяти случаях из десяти этого достаточно.
Чего в документации Laravel нет
Проблемы начинаются там, где нужно не найти метод, а принять архитектурное или эксплуатационное решение. Вот конкретные пробелы, с которыми я сталкивался на практике.
Страница Deployment описывает требования к серверу и оптимизацию конфигурации через artisan-команды кэширования, а из готовых вариантов деплоя предлагает Laravel Forge, Laravel Cloud и Vapor, то есть платные managed-сервисы. Если у команды обычный VPS с nginx и php-fpm, который нужно настраивать руками, готового чек-листа под этот сценарий в документации нет, придётся собирать его самому или у системного администратора.
По очередям в документации есть базовый пример конфигурации Supervisor для перезапуска воркера, но реальная эксплуатация, диагностика зависшего воркера, утечки памяти в долго живущем процессе, алерты при падении очереди, остаётся за кадром.
Сервис-контейнер на уровне основ (bind, singleton, contextual binding) объяснён понятно, а вот пограничные случаи в большом приложении с десятками провайдеров, порядок их загрузки, конфликты contextual binding между пакетами, документация не разбирает вообще.
Framework сознательно неопиньонированный за пределами MVC: как структурировать проект на 200+ моделей, стоит ли выносить бизнес-логику в Actions или Services, документация не советует, это решение читатель принимает сам или подсматривает в сторонних пакетах вроде Filament.
| Тема | Как покрыта в документации Laravel |
|---|---|
| Eloquent, роутинг, валидация | Подробно, с примером кода под каждый метод |
| Деплой на обычный VPS без managed-сервиса | Не описан, упор сделан на Forge, Cloud и Vapor |
| Эксплуатация очередей в проде | Только базовый пример Supervisor, без разбора сбоев |
| Архитектура крупного проекта | Не описана, только дефолтная MVC-структура |
Если на этом этапе выясняется, что нужен не самостоятельный разбор документации, а рабочий бэкенд, я беру такие проекты как разработку API или бэкенда на Laravel отдельной услугой, от 100 000 ₽.
Где искать то, чего нет в официальной документации
Когда официальных страниц не хватает, есть несколько проверенных источников.
- Laravel Bootcamp, официальный пошаговый туториал по сборке реального приложения, полезен именно как пример архитектурного решения, а не справочник по методам
- Laracasts с видеокурсами и разделом Discuss, где разработчики обсуждают конкретные production-сценарии, которых нет в docs
- Исходный код laravel/framework на GitHub, когда пример в документации не покрывает нужный edge case
- Laravel News, агрегатор новостей экосистемы и заметок о пакетах
- Stack Overflow и issues конкретных пакетов, если ошибка специфична для версии или связки пакетов
Laravel регулярно обновляется, поэтому перед внедрением я сверяюсь с актуальной документацией.
Частые вопросы
Нужно ли читать документацию Laravel целиком перед стартом проекта?
Нет, это не нужно и не эффективно. Я читаю подряд только Getting Started и Architecture Concepts, чтобы понимать общую логику фреймворка, а остальные разделы открываю по мере необходимости, когда работаю с конкретной фичей.
Как проверить, что я читаю документацию нужной версии Laravel?
Посмотрите версию в composer.json проекта или выполните php artisan --version, а затем переключите версию через выпадающий список в верхней части страницы на laravel.com/docs. Поведение методов и доступные опции отличаются между релизами.
Можно ли доверять переводам документации Laravel на русский язык?
Переводы от комьюнити обычно отстают от оригинала на несколько недель или месяцев, особенно после крупного релиза. Для страниц вроде Upgrade Guide и Security я всегда сверяюсь с английской версией, там цена ошибки в переводе выше.
Что делать, если в документации нет ответа на конкретную ошибку в проекте?
Сначала смотрю исходный код класса, который выбрасывает ошибку, через переход по определению в IDE. Если это не помогает, ищу issue в репозитории пакета на GitHub или обсуждение на Laracasts Discuss и Stack Overflow, там чаще всего уже разбирали похожий случай.