Laravel

01Жизненный цикл запроса

Каждый запрос входит через public/index.php. Laravel загружает приложение (сервис-провайдеры регистрируют биндинги и конфиг), а затем пропускает запрос через стек middleware — как через цепочку контрольных пунктов в аэропорту. Роутер сопоставляет URL и HTTP-метод с маршрутом, который вызывает метод контроллера. Контроллер что-то возвращает (модель, массив, Resource, view), и Laravel превращает это в HTTP-ответ, который уходит обратно через те же middleware. В Laravel 11+ вся эта связка находится в bootstrap/app.php: маршруты, middleware и обработку исключений регистрируют там, а не в отдельном классе Kernel. Знание этого порядка объясняет большинство багов: если не проходит авторизация — смотрите middleware; если данные неверные — смотрите контроллер и всё, что ниже.

• Сервис-провайдер: класс, который при загрузке регистрирует что-то в сервис-контейнере.
• Сервис-контейнер: система внедрения зависимостей в Laravel; он сам собирает классы и их зависимости.
• Middleware: код, который выполняется до или после контроллера (авторизация, троттлинг, локаль, CORS).

02Роутинг, middleware и тонкие контроллеры

Маршруты связывают URL с кодом. Группируйте их по аудитории и вешайте middleware на группу — тогда каждый маршрут внутри унаследует аутентификацию, лимиты запросов или локаль. Держите контроллеры тонкими: их задача — прочитать провалидированные входные данные, вызвать сервис, который делает реальную работу, и вернуть ответ. Бизнес-правила (как считается цена, когда заказ можно отменить) живут в сервисах или экшенах, а доступ к данным — в моделях. Такое разделение «контроллер → сервис → модель» позволяет вызывать одну и ту же логику из API-эндпоинта, Artisan-команды или задачи в очереди без копирования кода.

1// routes/api.php
2use App\Http\Controllers\Api\OrderController;
3use Illuminate\Support\Facades\Route;
4 
5Route::middleware(['auth:sanctum', 'throttle:api'])
6    ->prefix('v1')
7    ->group(function () {
8        Route::get('orders', [OrderController::class, 'index']);
9        Route::post('orders', [OrderController::class, 'store']);
10        Route::get('orders/{order}', [OrderController::class, 'show']);
11    });

03Валидация через FormRequest, ответ через API Resources

Валидируйте на входе. Класс FormRequest содержит правила и проверку authorize() для одного действия; если валидация не прошла, Laravel вернёт ответ 422 с ошибками по полям ещё до запуска контроллера. Внутри контроллера $request->validated() отдаёт только прошедшие проверку поля, что защищает от mass assignment. На выходе API Resource превращает модель ровно в ту форму JSON, которую ждут клиенты. Это отвязывает колонки базы данных от публичного контракта: можно переименовать колонку и не сломать мобильное приложение. Ещё Resources упрощают условные поля — например, включать связи, только если они были загружены.

1class StoreOrderRequest extends FormRequest
2{
3    public function authorize(): bool
4    {
5        return $this->user()->can('create', Order::class);
6    }
7 
8    public function rules(): array
9    {
10        return [
11            'items' => ['required', 'array', 'min:1'],
12            'items.*.product_id' => ['required', 'integer', 'exists:products,id'],
13            'items.*.qty' => ['required', 'integer', 'between:1,99'],
14            'note' => ['nullable', 'string', 'max:500'],
15        ];
16    }
17}

04Eloquent, связи и eager loading

Eloquent — это ORM в Laravel: каждый класс модели соответствует таблице, а связи (hasMany, belongsTo, belongsToMany, morphMany) — это методы модели. Классическая ловушка — проблема N+1: вы загружаете 50 заказов, затем в цикле обращаетесь к $order->customer, и Eloquent выполняет 50 лишних запросов. Eager loading через with() подтягивает связь одним дополнительным запросом. В разработке вызывайте Model::preventLazyLoading(), чтобы ленивая загрузка бросала исключение и вы ловили N+1 заранее. Используйте withCount() для подсчётов, выбирайте только нужные колонки для больших списков и пагинируйте всё, что пользователь может листать. Laravel 13 также позволяет настраивать многие свойства модели через PHP-атрибуты, но классические свойства по-прежнему работают.

1// AppServiceProvider::boot()
2Model::preventLazyLoading(! app()->isProduction());
3 
4// One query for orders, one for customers, one for items
5$orders = Order::query()
6    ->with(['customer:id,name', 'items.product:id,name,price'])
7    ->withCount('items')
8    ->where('status', OrderStatus::Paid)
9    ->latest()
10    ->paginate(20);
11 
12return OrderResource::collection($orders);

05Очереди, планировщик и аутентификация

Всё медленное или ненадёжное (письма, SMS, колбэки платежей, экспорты, синхронизация с ERP) уходит в задачу в очереди: пользователь быстро получает ответ, а воркер выполняет работу в фоне, с повторными попытками. Планировщик заменяет кучу записей в cron одной: cron каждую минуту запускает php artisan schedule:run, а само расписание описывается в routes/console.php. Для аутентификации по умолчанию выбирают Sanctum: сессии на cookie для вашего собственного SPA на том же домене верхнего уровня плюс простые персональные токены доступа для мобильных приложений. Passport — это полноценный OAuth2-сервер; выбирайте его, когда третьим сторонам нужны OAuth-флоу или вы уже завязаны на его модель токенов. Socialite добавляет вход через Google, Apple и другие соцсети поверх любого из них.

1// routes/console.php
2use Illuminate\Support\Facades\Schedule;
3 
4Schedule::command('subscriptions:expire')
5    ->dailyAt('02:00')
6    ->withoutOverlapping()
7    ->onOneServer();
8 
9Schedule::job(new SyncPricesFromErp)->hourly();
10 
11// crontab: * * * * * cd /var/www/app && php artisan schedule:run >> /dev/null 2>&1

06Советы для продакшена в эпоху Laravel 13

Работайте на PHP 8.3 или новее и везде используйте enum, readonly-свойства и типизированные сигнатуры. При деплое запускайте php artisan optimize, чтобы закэшировать конфиг, маршруты, события и view, и никогда не вызывайте env() вне конфиг-файлов, потому что закэшированный конфиг его игнорирует. Миграции запускайте отдельным шагом деплоя. Держите воркеры очередей под менеджером процессов и перезапускайте их на каждом деплое через php artisan queue:restart, иначе они продолжат выполнять старый код. Локально для отладки используйте Telescope или Pail, а в продакшене — структурированные логи и трекинг ошибок. В Laravel 13 также появились официальный AI SDK и JSON:API-ресурсы; берите их, когда они решают реальную задачу, а не потому что это новинка.

• Деплой: composer install --no-dev --optimize-autoloader, migrate --force, optimize, queue:restart.
• В продакшене ставьте APP_DEBUG=false: отладочные страницы раскрывают секреты.
• Оборачивайте многошаговые записи в транзакции базы данных и диспатчьте задачи через afterCommit.

07Сервис-контейнер, scope и долгоживущие воркеры

Классический PHP-FPM загружает Laravel на каждый запрос и потом всё выбрасывает, поэтому небрежное состояние редко вредит. Воркеры очередей и Octane (FrankenPHP, Swoole или RoadRunner) загружают приложение один раз и затем обслуживают тысячи запросов или задач из той же памяти. Это меняет правила. Биндинг, зарегистрированный через bind(), даёт новый объект при каждом резолве. singleton() даёт один объект на всё время жизни процесса — это правильно для stateless-клиентов, например HTTP-клиента платёжного шлюза. scoped() даёт один объект на запрос или на задачу и сбрасывается между ними — именно это нужно для всего, что хранит текущего пользователя, тенант или локаль. Положить данные запроса в singleton или статическое свойство — классический баг Octane: один клиент на мгновение видит контекст другого клиента.

1// AppServiceProvider::register()
2// Stateless client: safe to share for the whole process
3$this->app->singleton(PaymentGateway::class, fn () => new GatewayClient(
4    config('services.gateway.key'),
5));
6 
7// Holds per-request data: reset for every request and every queued job
8$this->app->scoped(CurrentTenant::class, fn () => new CurrentTenant());
9 
10// Cheap builder: a new instance on every resolve
11$this->app->bind(ReportBuilder::class);

08Eloquent на больших таблицах: chunking, lazy collections и strict mode

Order::all() на таблице с двумя миллионами строк загружает в память два миллиона моделей и убивает процесс. Для пакетной работы используйте chunkById(): он листает по первичному ключу и остаётся корректным, даже когда вы обновляете перебираемые строки (обычный chunk() со смещениями в этом случае пропускает строки). Для экспорта lazyById() возвращает LazyCollection, которая стримит строки почти с постоянным расходом памяти. Осторожнее с whereHas() на больших таблицах: он компилируется в коррелированный подзапрос EXISTS, который может быть медленным без подходящего составного индекса, и иногда join или whereIn с подзапросом намного быстрее. Model::shouldBeStrict() включает сразу три защиты: запрет lazy loading, исключение при установке атрибута, которого нет в fillable, вместо молчаливого игнорирования, и исключение при чтении атрибута, который не был выбран.

1// Backfill without loading everything
2Order::query()
3    ->where('status', OrderStatus::Paid)
4    ->whereNull('invoice_number')
5    ->chunkById(500, function ($orders) {
6        foreach ($orders as $order) {
7            GenerateInvoice::dispatch($order->id);
8        }
9    });
10 
11// Stream an export with near-constant memory
12foreach (Order::query()->select(['id', 'total', 'created_at'])->lazyById(1000) as $order) {
13    $csv->insertOne([$order->id, $order->total, $order->created_at]);
14}

09Гонки: атомарные обновления, блокировки строк и распределённые блокировки

Два покупателя одновременно покупают последний товар. Оба запроса читают stock = 1, оба проходят проверку, оба уменьшают остаток, и stock становится -1. Прочитать, проверить в PHP и потом записать — это никогда не безопасно при конкурентности. Самое дешёвое решение — атомарное условное обновление: пусть база проверит и изменит значение одним запросом, а вы посмотрите на количество затронутых строк. Когда нужно, чтобы несколько чтений и записей оставались согласованными, используйте транзакцию с lockForUpdate(), которая держит блокировку строки до коммита; делайте такие транзакции короткими и всегда блокируйте строки в одном и том же порядке, чтобы избежать deadlock. DB::transaction() принимает число попыток и повторяет при deadlock. Для работы, которая охватывает несколько процессов, например один импорт из ERP одновременно на всех серверах, используйте Cache::lock() с хранилищем Redis или базой данных. Уникальный индекс остаётся последней линией обороны.

1DB::transaction(function () use ($productId, $qty) {
2    $affected = Product::whereKey($productId)
3        ->where('stock', '>=', $qty)
4        ->decrement('stock', $qty);
5 
6    if ($affected === 0) {
7        throw new OutOfStockException($productId);
8    }
9}, attempts: 3);
10 
11// One import at a time across all servers (needs a shared cache store)
12Cache::lock('erp-import', 600)->block(5, function () {
13    app(ErpImporter::class)->run();
14});

10Укрепление Laravel API

Большинство проблем безопасности в Laravel — это конфигурация и привычки, а не баги фреймворка. Задайте именованные rate limiters для каждой аудитории: щедрые для залогиненных пользователей, строгие для анонимного трафика, очень строгие для OTP и сброса пароля, с ключом по пользователю, телефону и IP вместе. Ограничивайте вложенные route bindings через scopeBindings(), чтобы /shops/1/orders/99 падал, если заказ 99 принадлежит другому магазину. Используйте encrypted casts для чувствительных колонок вроде ИНН или токенов и помните, что ротация APP_KEY поддерживается через APP_PREVIOUS_KEYS: старые значения по-прежнему расшифровываются, а новые используют новый ключ. Используйте signed URLs для ссылок в письмах (отписка, скачивание), а не изобретайте свои токены. Держите шорткаты супер-админа в Gate::before узкими, потому что они обходят все политики. И наконец, запускайте composer audit в CI, чтобы ловить пакеты с известными уязвимостями.

1// AppServiceProvider::boot()
2RateLimiter::for('api', function (Request $request) {
3    return $request->user()
4        ? Limit::perMinute(120)->by('user:'.$request->user()->id)
5        : Limit::perMinute(30)->by('ip:'.$request->ip());
6});
7 
8RateLimiter::for('otp', fn (Request $request) => [
9    Limit::perMinute(1)->by('otp-phone:'.$request->input('phone')),
10    Limit::perDay(20)->by('otp-ip:'.$request->ip()),
11]);
12 
13// routes: ->middleware('throttle:otp')