Laravel

Откуда контейнер знает, что подставить

Через рефлексию. Контейнер читает сигнатуру конструктора, берёт тип каждого параметра и пытается разрешить его как класс. Если у того тоже есть зависимости — рекурсивно повторяет. Никаких XML- и YAML-конфигов, как в старых фреймворках.

В документации это называется Zero Configuration Resolution:

Где автоматическое внедрение работает

// Внедрение в метод, а не только в конструктор
public function store(StoreUserRequest $request, UserRepository $users)
{
    // И $request, и $users подставлены контейнером.
    // Параметры роута при этом тоже работают — они идут после зависимостей.
}

// Ручной вызов метода с внедрением зависимостей
$stats = App::call([new PodcastStats, 'generate']);
$result = App::call(function (AppleMusic $apple) { /* ... */ });

Что это значит на примере

Контроллеру нужно получать подкасты из внешнего источника. Вместо того чтобы создавать клиент внутри себя, он объявляет потребность — и получает её готовой.

namespace App\Http\Controllers;

use App\Services\AppleMusic;
use Illuminate\View\View;

class PodcastController extends Controller
{
    public function __construct(
        protected AppleMusic $apple,
    ) {}

    public function show(string $id): View
    {
        return view('podcasts.show', [
            'podcast' => $this->apple->findPodcast($id)
        ]);
    }
}

Главное следствие, на которое указывает документация: поскольку сервис внедряется, его легко подменить — мокнуть или подставить заглушку AppleMusic при тестировании. Если бы контроллер делал new AppleMusic внутри, тест бы полез в реальный Apple Music.

Куда именно «внедряются» зависимости

Simple Bindings — bind()

Назначение: объяснить контейнеру, как собрать объект, когда он не может догадаться сам. Новый объект на каждое разрешение.

Связь: абстракт → замыкание-фабрика. Замыкание получает контейнер и может разрешать подзависимости.

// Почти все биндинги регистрируются в сервис-провайдерах,
// где контейнер доступен через $this->app
$this->app->bind(Transistor::class, function (Application $app) {
    return new Transistor($app->make(PodcastParser::class));
});

// Вне провайдера — через фасад App
App::bind(Transistor::class, function (Application $app) { /* ... */ });

// Только если биндинга ещё нет — для пакетов, чтобы не перетирать приложение
$this->app->bindIf(Transistor::class, function (Application $app) { /* ... */ });

// Абстракт можно не указывать — он берётся из возвращаемого типа замыкания
App::bind(function (Application $app): Transistor {
    return new Transistor($app->make(PodcastParser::class));
});

Binding a Singleton — singleton()

Назначение: объект должен разрешаться один раз; все последующие обращения получают тот же экземпляр. Для дорогих в создании и не хранящих пользовательское состояние сервисов: менеджеры соединений, клиенты API, реестры.

Связь: абстракт → фабрика с shared = true; результат переезжает в $instances.

$this->app->singleton(Transistor::class, function (Application $app) {
    return new Transistor($app->make(PodcastParser::class));
});

$this->app->singletonIf(Transistor::class, function (Application $app) { /* ... */ });

app(Transistor::class) === app(Transistor::class);   // true

Singleton Attribute — то же самое без провайдера, пометкой на классе или интерфейсе:

use Illuminate\Container\Attributes\Singleton;

#[Singleton]
class Transistor {}

Binding Scoped Singletons — scoped()

Назначение: один экземпляр в пределах одного жизненного цикла запроса или джоба. Документация прямо указывает: такие экземпляры сбрасываются, когда Octane-воркер берёт новый запрос или queue-воркер — новый джоб.

Связь: как у singleton, плюс абстракт помечается в $scopedInstances; между циклами вызывается forgetScopedInstances().

$this->app->scoped(Transistor::class, function (Application $app) {
    return new Transistor($app->make(PodcastParser::class));
});

$this->app->scopedIf(Transistor::class, function (Application $app) { /* ... */ });

Scoped Attribute:

#[Scoped]
class Transistor {}

Binding Instances — instance()

Назначение: зарегистрировать уже созданный объект. Документация: заданный экземпляр будет возвращаться при всех последующих обращениях. Основное применение — подмена сервиса в тестах.

Связь: абстракт → конкретный объект, сразу в $instances. Фабрики нет.

$service = new Transistor(new PodcastParser);

$this->app->instance(Transistor::class, $service);

Binding Interfaces to Implementations

Назначение: главный случай, когда биндинг обязателен. Контейнер не может угадать, какую реализацию подставить вместо интерфейса.

Связь: интерфейс → класс реализации. Второй аргумент — строка, не замыкание: контейнер соберёт реализацию сам.

$this->app->bind(EventPusher::class, RedisEventPusher::class);

// Теперь интерфейс объявляется в конструкторе любого класса,
// который создаётся контейнером
public function __construct(
    protected EventPusher $pusher,
) {}

Bind Attribute — то же решение прямо на интерфейсе, без регистрации в провайдере. Несколько #[Bind] задают разные реализации под разные окружения:

use Illuminate\Container\Attributes\Bind;

#[Bind(RedisEventPusher::class)]
#[Bind(FakeEventPusher::class, environments: ['local', 'testing'])]
interface EventPusher {}

// Время жизни задаётся тут же
#[Bind(RedisEventPusher::class)]
#[Singleton]
interface EventPusher {}

#[BindWhen] — реализация по произвольному условию. Замыкание получает контейнер и возвращает true, когда биндинг нужно применить. Bind и BindWhen вычисляются в порядке объявления.

use Illuminate\Container\Attributes\BindWhen;

#[BindWhen(BetaEventPusher::class, static fn () => Feature::active('beta-events'))]
interface EventPusher {}

Contextual Binding

Назначение: два класса зависят от одного интерфейса, но каждому нужна своя реализация.

Связь: трёхместная — (кто запрашивает) + (что ему нужно) → что подставить.

$this->app->when(PhotoController::class)
    ->needs(Filesystem::class)
    ->give(function () {
        return Storage::disk('local');
    });

// Одно правило на несколько потребителей
$this->app->when([VideoController::class, UploadController::class])
    ->needs(Filesystem::class)
    ->give(function () {
        return Storage::disk('s3');
    });

Contextual Attributes

Назначение: контекстный биндинг чаще всего нужен для драйверов и значений конфига — атрибуты позволяют не описывать его в провайдере вообще.

Связь: конкретный параметр → источник значения, объявляется прямо в сигнатуре.

public function __construct(
    #[Auth('web')]                    protected Guard $auth,
    #[Cache('redis')]                  protected Repository $cache,
    #[Config('app.timezone')]          protected string $timezone,
    #[Context('uuid')]                  protected string $uuid,
    #[Context('ulid', hidden: true)]   protected string $ulid,
    #[DB('mysql')]                     protected Connection $connection,
    #[Give(DatabaseRepository::class)] protected UserRepository $users,
    #[Log('daily')]                    protected LoggerInterface $log,
    #[RequestAttribute('organization')] protected Organization $organization,
    #[RouteParameter]                 protected Photo $photo,
    #[Storage('local')]                protected Filesystem $filesystem,
    #[Tag('reports')]                  protected iterable $reports,
) {}

// Текущий пользователь — отдельным атрибутом, работает и в роуте
Route::get('/user', fn (#[CurrentUser] User $user) => $user)
    ->middleware('auth');

• #[RouteParameter] разрешает параметр маршрута по имени переменной; имя указывается явно только при несовпадении — #[RouteParameter('photo')].
• #[RequestAttribute('organization')] берёт значение из attribute bag запроса — того, куда middleware кладёт данные через $request->attributes->set().

Свои атрибуты — в подразделе «Свой контекстный атрибут» ниже.

Binding Primitives

Назначение: классу нужен не объект, а скалярное значение — число, строка, массив. Контейнер такое через рефлексию не разрешит.

Связь: (потребитель) + (имя переменной со знаком $) → значение.

// Обычное значение
$this->app->when(UserController::class)
    ->needs('$variableName')
    ->give($value);

// Массив всех биндингов с тегом
$this->app->when(ReportAggregator::class)
    ->needs('$reports')
    ->giveTagged('reports');

// Значение из файла конфигурации
$this->app->when(ReportAggregator::class)
    ->needs('$timezone')
    ->giveConfig('app.timezone');

Обрати внимание на знак $ внутри строки: он и отличает примитивный параметр от типа класса.

Binding Typed Variadics

Назначение: конструктор принимает переменное число типизированных объектов — Filter ...$filters.

Связь: (потребитель) + (тип элемента) → массив реализаций.

class Firewall
{
    protected $filters;

    public function __construct(
        protected Logger $logger,
        Filter ...$filters,
    ) {
        $this->filters = $filters;
    }
}

// Замыканием — когда нужен контроль над сборкой каждого
$this->app->when(Firewall::class)
    ->needs(Filter::class)
    ->give(function (Application $app) {
        return [
            $app->make(NullFilter::class),
            $app->make(ProfanityFilter::class),
            $app->make(TooLongFilter::class),
        ];
    });

// Короче — просто массив имён классов
$this->app->when(Firewall::class)
    ->needs(Filter::class)
    ->give([
        NullFilter::class,
        ProfanityFilter::class,
        TooLongFilter::class,
    ]);

Variadic Tag Dependencies — если вариативная зависимость типизирована (Report ...$reports), всю группу по тегу можно отдать одной строкой:

$this->app->when(ReportAggregator::class)
    ->needs(Report::class)
    ->giveTagged('reports');

Tagging

Назначение: разрешить сразу всю «категорию» биндингов — например, все реализации интерфейса Report для анализатора отчётов.

Связь: тег → список абстрактов. Сам тег ничего не создаёт, он только группирует уже зарегистрированные биндинги.

$this->app->bind(CpuReport::class, function () { /* ... */ });
$this->app->bind(MemoryReport::class, function () { /* ... */ });

$this->app->tag([CpuReport::class, MemoryReport::class], 'reports');

// Разрешить всю группу
$this->app->bind(ReportAnalyzer::class, function (Application $app) {
    return new ReportAnalyzer($app->tagged('reports'));
});

Extending Bindings — extend()

Назначение: изменить уже разрешённый сервис — обернуть декоратором или донастроить, не переписывая исходный биндинг.

Связь: абстракт → замыкание-декоратор. Замыкание получает собранный сервис и контейнер, возвращает замену.

$this->app->extend(Service::class, function (Service $service, Application $app) {
    return new DecoratedService($service);
});

Применяется на каждое разрешение, поэтому расширителей может быть несколько — они накладываются друг на друга в порядке регистрации.

Resolving — make(), makeWith(), bound()

Назначение: достать объект из контейнера вручную, когда автоматическое внедрение неприменимо.

$transistor = $this->app->make(Transistor::class);

// Если часть зависимостей контейнер разрешить не может — передать руками
$transistor = $this->app->makeWith(Transistor::class, ['id' => 1]);

// Есть ли явный биндинг
if ($this->app->bound(Transistor::class)) { /* ... */ }

// Там, где нет $app
$transistor = App::make(Transistor::class);
$transistor = app(Transistor::class);

// Сам контейнер можно получить внедрением
public function __construct(
    protected Container $container,
) {}

Automatic Injection

Назначение: основной способ получения зависимостей. Документация: «в практике именно так большинство объектов и должно разрешаться контейнером».

Тип объявляется в конструкторе класса, который создаёт контейнер — контроллеры, listeners, middleware и прочие. У джобов зависимости объявляются в handle().

class PodcastController extends Controller
{
    public function __construct(
        protected AppleMusic $apple,
    ) {}

    public function show(string $id): Podcast
    {
        return $this->apple->findPodcast($id);
    }
}

Method Invocation and Injection — App::call()

Назначение: вызвать метод на объекте так, чтобы контейнер сам подставил зависимости этого метода. Принимает любой PHP callable, включая замыкание.

class PodcastStats
{
    public function generate(AppleMusic $apple): array
    {
        return [ /* ... */ ];
    }
}

$stats = App::call([new PodcastStats, 'generate']);

$result = App::call(function (AppleMusic $apple) {
    // ...
});

Что означает «resolve»

Resolve (разрешить) — процесс, в котором контейнер создаёт объект и подставляет все его зависимости. «Разрешить» здесь значит «удовлетворить все требования класса»: найти и передать всё, что он просит в конструкторе.

Когда ты пишешь app(Transistor::class) — или когда контейнер сам создаёт контроллер — происходит ровно это:

1. Контейнер смотрит на класс Transistor.
2. Читает его конструктор через рефлексию.
3. Для каждого параметра конструктора находит зависимость — рекурсивно, то есть у зависимостей тоже разрешаются их зависимости.
4. Создаёт объект: new Transistor(...$dependencies).
5. Возвращает готовый экземпляр.

Весь этот процесс и называется resolve. Результат — собранный объект.

Полный порядок внутри resolve()

Понимать порядок важно: от него зависит, что можно сделать на каком этапе. Это фактическая последовательность из Container::resolve():

resolving() — подписка на создание объекта

Назначение: донастроить объект после сборки, но до того, как он уйдёт потребителю. Колбэк получает сам объект и контейнер.

// Для конкретного типа
$this->app->resolving(Transistor::class, function (Transistor $transistor, Application $app) {
    $transistor->setDebugMode($app->isLocal());
});

// Без первого аргумента — на ЛЮБОЙ объект, для отладки и аудита
$this->app->resolving(function (mixed $object, Application $app) {
    Log::info('Resolved: ' . get_class($object));
});

// beforeResolving — до сборки, объекта ещё нет, есть только тип и параметры
$this->app->beforeResolving(Transistor::class, function ($abstract, $parameters, $app) {});

// afterResolving — сразу после resolving, тоже до возврата
$this->app->afterResolving(Transistor::class, function (Transistor $transistor) {
    $transistor->boot();
});

Три вещи, в которых легко ошибиться

Rebinding — подписка на переопределение биндинга

Назначение: отследить, что сервис перебиндили — зарегистрировали заново или переопределили после первого биндинга. Это не то же самое, что resolving: тут событие про изменение правила, а не про создание объекта.

$this->app->bind(PodcastPublisher::class, SpotifyPublisher::class);

$this->app->rebinding(
    PodcastPublisher::class,
    function (Application $app, PodcastPublisher $newInstance) {
        //
    },
);

// Новый биндинг запустит замыкание выше
$this->app->bind(PodcastPublisher::class, TransistorPublisher::class);

Сахар над этим — refresh($abstract, $target, $method): подписывается на переопределение и сам вызывает сеттер у объекта, который держит устаревшую зависимость.

PSR-11

Контейнер Laravel реализует интерфейс PSR-11, поэтому в типе можно объявлять стандартный ContainerInterface.

use Psr\Container\ContainerInterface;

Route::get('/', function (ContainerInterface $container) {
    $service = $container->get(Transistor::class);
});

1. Создание и загрузка

Вот как это выглядит в этом проекте — public/index.php почти пустой, вся работа в двух строках:

require __DIR__.'/../vendor/autoload.php';

$app = require_once __DIR__.'/../bootstrap/app.php';   // ← контейнер

$app->handleRequest(Request::capture());

И artisan — тот же контейнер, другой вход:

$app = require_once __DIR__.'/bootstrap/app.php';

$status = $app->handleCommand(new ArgvInput);

2. Где регистрируются биндинги

// app/Providers/AppServiceProvider.php
public function register(): void
{
    $this->app->bind(PaymentGateway::class, StripeGateway::class);
    $this->app->singleton(ReportGenerator::class);
}

// bootstrap/app.php — без создания провайдера
return Application::configure(basePath: dirname(__DIR__))
    ->withBindings([PaymentGateway::class => StripeGateway::class])
    ->withSingletons([ReportGenerator::class])
    ->create();

В этом проекте bootstrap/providers.php минимальный — один провайдер:

return [
    AppServiceProvider::class,
];

3. Где контейнер работает через DI

Здесь ты его не вызываешь — он сам подставляет зависимости по типам в сигнатуре.

// Контроллер
class OrderController extends Controller
{
    public function __construct(private PaymentGateway $gateway) {}
}

// Middleware
class CheckRole
{
    public function __construct(private RoleService $roles) {}
}

// Artisan-команда — зависимости в handle()
class SendReports extends Command
{
    public function handle(ReportService $service)
    {
        $service->send();
    }
}

// Замыкание роута — можно и типом, и вручную
Route::get('/test', function (OrderService $service) {   // предпочтительно
    return $service->run();
});

Route::get('/test', function () {
    return app(OrderService::class)->run();   // тоже работает
});

4. Хелперы и фасады — ручной доступ

5. Где контейнер реализован

Внутри vendor, но знать полезно — я сверялся с этими файлами по всему разделу.

Итог одной картинкой

Прямо руками контейнер трогают в основном в провайдерах. Везде остальное он работает сам — и именно поэтому его легко не замечать.

Сначала — сервисы это не контейнеры

Частая путаница: кажется, что «DI-контейнеры» — это папка app/Services. Нет. Контейнер один на всё приложение, сервисов — много.

Аналогия: контейнер — склад деталей и сборщик; сервисы — изделия, которые из деталей собираются; контроллеры, джобы и команды — заказчики. Склад один, изделий много, заказчиков ещё больше.

Пример 1: рекурсивное разрешение цепочки

Показывает главное свойство контейнера: он собирает весь граф объектов, а не один объект.

// Нижний уровень — без зависимостей
class Logger
{
    public function log(string $message): void
    {
        Log::info($message);
    }
}

// Зависит от логгера
class OrderRepository
{
    public function __construct(private Logger $logger) {}

    public function save(array $data): void
    {
        $this->logger->log('Saving order: ' . json_encode($data));
    }
}

// Зависит от ПРИМИТИВА — автоматически не соберётся, нужен биндинг
class StripeGateway
{
    public function __construct(private string $apiKey) {}

    public function charge(float $amount): bool { return true; }
}

// Верхний уровень
class OrderService
{
    public function __construct(
        private OrderRepository $repository,
        private StripeGateway $gateway,
    ) {}

    public function process(array $data): void
    {
        $this->repository->save($data);
        $this->gateway->charge($data['total']);
    }
}

Единственное, что нужно зарегистрировать — класс с примитивом в конструкторе:

// AppServiceProvider::register()
$this->app->bind(StripeGateway::class, function ($app) {
    return new StripeGateway(config('services.stripe.key'));
});

Что происходит на app(OrderService::class):

Контейнер спускается по графу вниз, а собирает снизу вверх: Logger → OrderRepository → замыкание для StripeGateway → OrderService. Ни одной строки new ты не пишешь — только одна регистрация там, где контейнер угадать не может.

Использование — просто тип в сигнатуре:

class OrderController extends Controller
{
    public function store(Request $request, OrderService $service)
    {
        $service->process($request->validated());

        return response()->noContent();
    }
}

Пример 2: внешний SDK за интерфейсом

Внешние SDK (Stripe, AWS, Twilio) не рассчитаны на DI: свои конструкторы, статические методы, глобальные ключи. Решение — адаптер за своим интерфейсом.

// 1. Контракт — то, что знает твой код
namespace App\Contracts;

interface PaymentGateway
{
    public function charge(float $amount, string $currency = 'usd'): array;
    public function refund(string $chargeId, float $amount): array;
}

// 2. Адаптер — SDK заперт внутри, наружу не торчит
class StripePaymentGateway implements PaymentGateway
{
    private StripeClient $client;

    public function __construct(string $apiKey)
    {
        $this->client = new StripeClient($apiKey);
    }

    public function charge(float $amount, string $currency = 'usd'): array
    {
        return $this->client->charges->create([
            'amount'   => $amount * 100,
            'currency' => $currency,
        ])->toArray();
    }

    public function refund(string $chargeId, float $amount): array
    {
        return $this->client->refunds->create([
            'charge' => $chargeId,
            'amount' => $amount * 100,
        ])->toArray();
    }
}

// 3. Фейк для тестов и локальной разработки — тот же контракт
class FakePaymentGateway implements PaymentGateway
{
    public function charge(float $amount, string $currency = 'usd'): array
    {
        return ['id' => 'fake_charge_' . uniqid(), 'status' => 'succeeded'];
    }

    public function refund(string $chargeId, float $amount): array
    {
        return ['id' => 'fake_refund_' . uniqid(), 'status' => 'succeeded'];
    }
}

Биндинг решает, какая реализация поедет в прод, а какая — в тесты:

// AppServiceProvider::register()
// singleton, а не bind: SDK-клиент дорог в создании и состояния запроса не держит
$this->app->singleton(PaymentGateway::class, function ($app) {
    return $app->environment('production')
        ? new StripePaymentGateway(config('services.stripe.key'))
        : new FakePaymentGateway();
});

Либо то же самое атрибутом на интерфейсе, вообще без провайдера:

#[Bind(StripePaymentGateway::class)]
#[Bind(FakePaymentGateway::class, environments: ['local', 'testing'])]
interface PaymentGateway {}

Код-потребитель не знает, что под капотом:

class CheckoutController extends Controller
{
    public function __construct(private PaymentGateway $gateway) {}

    public function pay(Request $request)
    {
        return response()->json($this->gateway->charge($request->total));
    }
}

Пример 3: свой сервис в контроллере, джобе и тесте

Тот же приём без внешних SDK — простой биндинг интерфейса на класс.

interface PaymentService
{
    public function charge(User $user, Order $order): bool;
    public function refund(Order $order): bool;
}

class DefaultPaymentService implements PaymentService
{
    public function __construct(private Logger $logger) {}

    public function charge(User $user, Order $order): bool
    {
        return DB::transaction(function () use ($user, $order) {
            $this->logger->log("Charging user {$user->id} for order {$order->id}");

            $order->update(['status' => 'paid']);

            return true;
        });
    }

    public function refund(Order $order): bool
    {
        $this->logger->log("Refunding order {$order->id}");
        $order->update(['status' => 'refunded']);

        return true;
    }
}

// Биндинг — одна строка, замыкание не нужно: Logger собирается сам
$this->app->bind(PaymentService::class, DefaultPaymentService::class);

В контроллере — конструктор:

class OrderController extends Controller
{
    public function __construct(private PaymentService $payment) {}

    public function pay(Request $request, Order $order)
    {
        $this->payment->charge($request->user(), $order);

        return redirect()->route('orders.show', $order);
    }
}

В джобе — данные в конструктор, сервисы в handle():

class ProcessPayment implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(
        private User $user,
        private Order $order,
    ) {}

    public function handle(PaymentService $payment): void
    {
        $payment->charge($this->user, $this->order);
    }
}

В тесте — подмена через instance():

public function test_order_can_be_paid(): void
{
    $this->app->instance(PaymentService::class, new FakePaymentService);

    $this->post('/orders/1/pay')->assertRedirect();
}

instance() кладёт объект прямо в $instances, а он проверяется первым — поэтому подмена перебивает любой существующий биндинг.

Что показывает каждый пример

Что делает контейнер без атрибута

Порядок разрешения параметра такой:

• Имя параметра совпадает с именем параметра маршрута ({user} → $user) и тип — Eloquent-модель → срабатывает implicit route model binding.
• Тип — класс, совпадения с маршрутом нет → контейнер создаёт объект. Для User $user это будет new User — пустая модель, не связанная с текущим пользователем.
• Тип — примитив → Laravel ищет значение среди параметров маршрута.

Второй пункт и есть причина, по которой #[CurrentUser] вообще нужен: без него ты получишь не текущего пользователя, а пустую модель.

#[CurrentUser] — текущий аутентифицированный

// Illuminate\Container\Attributes\Authenticated — реальная реализация
public function __construct(public ?string $guard = null) {}

public static function resolve(self $attribute, Container $container)
{
    return call_user_func($container->make('auth')->userResolver(), $attribute->guard);
}

Эквивалент auth()->user() внутри метода. Можно указать guard: #[CurrentUser('api')].

#[RouteParameter('name')] — значение из URL

Нужен, когда имя переменной не совпадает с именем параметра маршрута.

// Имена совпадают → атрибут не нужен, работает implicit binding
Route::get('/users/{user}', fn (User $user) => $user);

// Имена НЕ совпадают: в URL {user}, а переменная $profile
Route::get('/users/{user}', fn (#[RouteParameter('user')] User $profile) => $profile);

Полный список атрибутов в Laravel 13

#[DB] — алиас #[Database], ровно как #[CurrentUser] для #[Authenticated].

Нужен атрибут для данных из middleware? Его придётся написать

Для данных из $request->attributes в актуальной версии есть штатный #[RequestAttribute('ключ')] — он читает значение из attribute bag запроса. Если его в проекте нет (появился в ветке 13.x позже 13.6.0), тот же атрибут делается самостоятельно — и это заодно канонический пример своего контекстного атрибута:

// Middleware кладёт данные
$request->attributes->set('tenant', Tenant::find(1));

// Свой атрибут — контракт ContextualAttribute + статический resolve()
use Illuminate\Contracts\Container\ContextualAttribute;

#[Attribute(Attribute::TARGET_PARAMETER)]
class RequestAttribute implements ContextualAttribute
{
    public function __construct(public string $key, public mixed $default = null) {}

    public static function resolve(self $attribute, Container $container)
    {
        return $container->make('request')->attributes->get($attribute->key, $attribute->default);
    }
}

// Теперь можно так
Route::get('/dashboard', fn (#[RequestAttribute('tenant')] Tenant $tenant) => $tenant);

Когда атрибут нужен, а когда нет

Всё вместе

Route::get('/organizations/{organization}/users/{user}', function (
    #[RouteParameter('organization')] Organization $org,
    #[RouteParameter('user')]         User $targetUser,
    #[CurrentUser]                   User $currentUser,
    #[Config('app.timezone')]       string $timezone,
) {
    // $org, $targetUser — из URL
    // $currentUser     — из auth
    // $timezone        — из config
})->middleware('auth');

Контекстные атрибуты появились в ветке Laravel 11 и убирают из тела метода ручные app()->make(), auth()->user(), config() — источник данных виден прямо в сигнатуре.

Анатомия

use Illuminate\Contracts\Container\Container;
use Illuminate\Contracts\Container\ContextualAttribute;

#[Attribute(Attribute::TARGET_PARAMETER)]   // 1. где разрешено вешать
class Config implements ContextualAttribute   // 2. маркер для контейнера
{
    public function __construct(
        public string $key,
        public mixed $default = null,
    ) {}

    // 3. контейнер вызовет это сам
    public static function resolve(self $attribute, Container $container): mixed
    {
        return $container->make('config')->get($attribute->key, $attribute->default);
    }
}

Три уровня, которые легко спутать

TARGET_PARAMETER ничего не подставляет. Это только ограничение области применения — есть ещё TARGET_CLASS, TARGET_METHOD, TARGET_PROPERTY, TARGET_ALL. Поменяешь на TARGET_CLASS — атрибут станет нельзя вешать на параметр, PHP выдаст ошибку при разборе класса, но логика resolve() останется той же.

Свойства называй как угодно: $key, $store, $default — важно лишь, чтобы resolve() их использовал.

Как контейнер различает атрибуты на разных параметрах

Через рефлексию: атрибут привязан к конкретному параметру, и для каждого создаётся свой экземпляр со своими значениями.

// Illuminate\Container\Util
public static function getContextualAttributeFromDependency($dependency)
{
    return $dependency->getAttributes(
        ContextualAttribute::class, ReflectionAttribute::IS_INSTANCEOF
    )[0] ?? null;
}

Комбинировать разные атрибуты в одном конструкторе можно свободно — каждый резолвится своим классом:

public function __construct(
    #[Config('reports.format')]  private string $format,     // config()
    #[CurrentUser]                 private User $user,         // auth()
    #[RouteParameter('report')]   private Report $report,     // request()->route()
    #[FromCache('reports.latest')] private array $cached,      // свой атрибут
) {}

Атрибут с несколькими свойствами и именованными аргументами

#[Attribute(Attribute::TARGET_PARAMETER)]
class FromCache implements ContextualAttribute
{
    public function __construct(
        public string $key,
        public ?string $store = null,
        public mixed $default = null,
    ) {}

    public static function resolve(self $attribute, Container $container): mixed
    {
        $cache = $container->make('cache');

        if ($attribute->store) {
            $cache = $cache->store($attribute->store);
        }

        return $cache->get($attribute->key, $attribute->default);
    }
}

// Именованные аргументы работают как в обычном конструкторе
public function __construct(
    #[FromCache('stats.daily')]                                  private array $daily,
    #[FromCache('stats.weekly', store: 'redis', default: [])] private array $weekly,
) {}

Альтернатива resolve(): внешний handler

Метод resolve() в самом атрибуте — не единственный путь. Handler можно зарегистрировать снаружи, в провайдере. Полезно, когда атрибут приходит из чужого пакета и править его нельзя.

// AppServiceProvider::boot()
$this->app->whenHasAttribute(CurrentTenant::class, function ($attribute, $container) {
    return $container->make(TenantContext::class)->current();
});

Приоритет такой: сначала контейнер ищет зарегистрированный handler, и только если его нет — статический resolve() на атрибуте. Если нет ни того, ни другого:

BindingResolutionException: Contextual binding attribute [App\Attributes\X]
has no registered handler.

Хук after() — донастройка уже созданного объекта

Помимо resolve() контейнер поддерживает необязательный метод after(): он вызывается после того, как объект разрешён, и позволяет его донастроить.

// Container::fireAfterResolvingAttributeCallbacks()
if (method_exists($instance, 'after')) {
    $instance->after($instance, $object, $this);
}

Простой пример: текущий тенант

#[Attribute(Attribute::TARGET_PARAMETER)]
class CurrentTenant implements ContextualAttribute
{
    public static function resolve(self $attribute, Container $container): Tenant
    {
        return $container->make(TenantContext::class)->current();
    }
}

// Конструктор атрибуту не нужен — ему нечего принимать
class ReportController
{
    public function index(#[CurrentTenant] Tenant $tenant)
    {
        return view('reports', compact('tenant'));
    }
}

Связка с мультитенантностью разобрана в KB_5 → Мультитенантность: такой атрибут — аккуратная замена вызову tenant() в теле каждого метода.

Обычный атрибут против контекстного

Как написать провайдер

Все провайдеры наследуют Illuminate\Support\ServiceProvider и обычно содержат два метода — register и boot.

php artisan make:provider RiakServiceProvider

Artisan сгенерирует класс и сам пропишет его в bootstrap/providers.php.

Метод register()

Внутри любого метода провайдера доступно свойство $app — это контейнер.

namespace App\Providers;

use App\Services\Riak\Connection;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\ServiceProvider;

class RiakServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton(Connection::class, function (Application $app) {
            return new Connection(config('riak'));
        });
    }
}

Свойства $bindings и $singletons

Если провайдер регистрирует много простых биндингов, вместо ручных вызовов можно объявить два свойства. Фреймворк проверит их при загрузке провайдера и зарегистрирует сам.

class AppServiceProvider extends ServiceProvider
{
    /** Все биндинги, которые нужно зарегистрировать. */
    public $bindings = [
        ServerProvider::class => DigitalOceanServerProvider::class,
    ];

    /** Все синглтоны, которые нужно зарегистрировать. */
    public $singletons = [
        DowntimeNotifier::class => PingdomDowntimeNotifier::class,
        ServerProvider::class    => ServerToolsProvider::class,
    ];
}

Обрабатывается это в Application: при регистрации провайдера фреймворк проходит foreach ($provider->bindings ...) и foreach ($provider->singletons ...). Только формат «интерфейс ⇒ класс»; замыкание так не задать.

Метод boot()

А что если нужно зарегистрировать view composer? Это делается в boot(). Метод вызывается после того, как зарегистрированы все остальные провайдеры — значит, доступны все сервисы, которые успел зарегистрировать фреймворк.

class ComposerServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        View::composer('view', function () {
            // ...
        });
    }
}

Внедрение зависимостей в boot(). Его аргументы можно типизировать — контейнер подставит что нужно:

use Illuminate\Contracts\Routing\ResponseFactory;

public function boot(ResponseFactory $response): void
{
    $response->macro('serialized', function (mixed $value) {
        // ...
    });
}

register() против boot()

Регистрация провайдеров

Все провайдеры перечислены в bootstrap/providers.php — файл возвращает массив имён классов.

// bootstrap/providers.php
return [
    App\Providers\AppServiceProvider::class,
];

Команда make:provider добавляет новый провайдер в этот массив автоматически. Если класс создан руками — дописать нужно самому:

return [
    App\Providers\AppServiceProvider::class,
    App\Providers\ComposerServiceProvider::class,
];

Отложенные провайдеры (Deferred Providers)

Если провайдер только регистрирует биндинги в контейнер, его загрузку можно отложить до момента, когда один из этих биндингов реально понадобится. Это ускоряет приложение: провайдер не читается с диска на каждый запрос.

Laravel компилирует и хранит список всех сервисов, которые предоставляются отложенными провайдерами, вместе с именем класса провайдера. Провайдер подгружается только при попытке разрешить один из этих сервисов.

Чтобы отложить загрузку — реализуй Illuminate\Contracts\Support\DeferrableProvider и опиши метод provides(), возвращающий зарегистрированные биндинги:

use Illuminate\Contracts\Support\DeferrableProvider;

class RiakServiceProvider extends ServiceProvider implements DeferrableProvider
{
    public function register(): void
    {
        $this->app->singleton(Connection::class, function (Application $app) {
            return new Connection($app['config']['riak']);
        });
    }

    /** @return array<int, string> */
    public function provides(): array
    {
        return [Connection::class];
    }
}

Хелперы — дополнение к фасадам

В дополнение к фасадам есть глобальные хелперы: view, response, url, config и другие. Они доступны глобально, импортировать классы не нужно.

use Illuminate\Support\Facades\Response;

Route::get('/users', function () {
    return Response::json([ /* ... */ ]);
});

Route::get('/users', function () {
    return response()->json([ /* ... */ ]);
});

Когда использовать фасады

Плюсы: короткий запоминающийся синтаксис, не нужно держать в голове длинные имена классов и внедрять их вручную. За счёт динамических методов PHP они при этом легко тестируются.

Фасады против внедрения зависимостей

Главный плюс DI — возможность подменить реализацию. Обычный статический метод подменить нельзя. Но фасады используют динамические методы, проксируя вызовы к объекту из контейнера, — поэтому тестируются они так же, как внедрённый экземпляр.

Route::get('/cache', function () {
    return Cache::get('key');
});

// Тест: проверяем, что Cache::get вызвался с нужным аргументом
public function test_basic_example(): void
{
    Cache::shouldReceive('get')
        ->with('key')
        ->andReturn('value');

    $this->get('/cache')->assertSee('value');
}

Фасады против хелперов

Многие хелперы делают ровно то же, что соответствующий фасад. Эти два вызова эквивалентны:

return Illuminate\Support\Facades\View::make('profile');

return view('profile');

Как фасады работают внутри

Фасад — класс, дающий доступ к объекту из контейнера. Вся механика в базовом Illuminate\Support\Facades\Facade, который использует магический метод __callStatic(), чтобы переадресовать вызов объекту, разрешённому из контейнера.

Если заглянуть в Illuminate\Support\Facades\Cache, никакого статического метода get там нет — весь класс выглядит так:

class Cache extends Facade
{
    /** Получить зарегистрированное имя компонента. */
    protected static function getFacadeAccessor(): string
    {
        return 'cache';
    }
}

Задача getFacadeAccessor() — вернуть имя биндинга в контейнере. Когда ты обращаешься к любому статическому методу фасада, Laravel разрешает биндинг cache из контейнера и выполняет запрошенный метод на полученном объекте.

// Illuminate\Support\Facades\Facade — ядро механизма
public static function __callStatic($method, $args)
{
    $instance = static::getFacadeRoot();

    if (! $instance) {
        throw new RuntimeException('A facade root has not been set.');
    }

    return $instance->$method(...$args);
}

То есть Cache::get('key') разворачивается в app('cache')->get('key'). Фасад проксирует к контракту Illuminate\Contracts\Cache\Factory.

Фасад, хелпер или DI — что выбирать

Real-Time Facades

Любой свой класс можно использовать как фасад. Без них, чтобы опубликовать подкаст, пришлось бы прокидывать Publisher аргументом:

class Podcast extends Model
{
    public function publish(Publisher $publisher): void
    {
        $this->update(['publishing' => now()]);

        $publisher->publish($this);
    }
}

Внедрение позволяет тестировать метод изолированно, но заставляет передавать Publisher при каждом вызове. Real-time facade сохраняет тестируемость и убирает аргумент. Чтобы его получить, добавь к пространству имён импортируемого класса префикс Facades:

use Facades\App\Contracts\Publisher;

class Podcast extends Model
{
    public function publish(): void
    {
        $this->update(['publishing' => now()]);

        Publisher::publish($this);
    }
}

Реализация разрешается из контейнера по той части имени, что идёт после префикса Facades. В тестах мокается штатными хелперами:

use Facades\App\Contracts\Publisher;

public function test_podcast_can_be_published(): void
{
    $podcast = Podcast::factory()->create();

    Publisher::shouldReceive('publish')->once()->with($podcast);

    $podcast->publish();
}

Справочник фасадов

Каждый фасад и класс, который за ним стоит. Третья колонка — ключ биндинга в контейнере, где он есть.

Строки вида «Auth (Instance)» означают, что фасад может указывать и на менеджер, и на конкретный экземпляр драйвера — в зависимости от того, какой метод вызван.

DI (Dependency Injection)

Внедрение зависимостей — зависимости не создаются внутри класса, а передаются извне. Класс перестаёт «знать», как строить свои сервисы — он их только принимает и использует.

// Без DI — класс сам создаёт зависимость
class UserService {
    public function save() {
        $db = new PDO('mysql:...');   // жёстко привязан к PDO
        $db->exec(...);
    }
}

// С DI — зависимость передаётся снаружи
class UserService {
    public function __construct(private PDO $db) {}
    public function save() {
        $this->db->exec(...);
    }
}

Laravel-контейнер сам разрешает эти зависимости при вызове: увидит PDO $db в конструкторе → сам создаст или подставит singleton. Подробнее — в KB_13 Service Container.

Декларативный vs Императивный

Пример в Laravel: старый Laravel 10 требовал императивно править 3 файла — регистрируй middleware в $middleware, обработчик в Handler::register(). Laravel 11+ — декларативно: «мои middleware — вот эти, мои исключения — вот такие», а как это подключить — забота фреймворка.

Провайдеры (Service Providers)

Классы, где ты регистрируешь свои сервисы в контейнере и бутстрапишь их. Два ключевых метода:

• register() — только биндинги в контейнер: $this->app->bind(PaymentGateway::class, StripeGateway::class). Никаких обращений к другим сервисам — они могут быть ещё не зарегистрированы.
• boot() — вызывается, когда всё зарегистрировано: сюда вешаешь Blade-директивы, observers, policies, кастомные валидаторы, макросы для коллекций/query builder.

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Только биндинги — другие сервисы ещё могут быть не готовы
        $this->app->bind(PaymentGateway::class, StripeGateway::class);
        $this->app->singleton(Cache::class, fn() => new RedisCache());
    }

    public function boot(): void
    {
        // Всё зарегистрировано — можно вешать хуки, макросы, директивы
        Blade::directive('money', fn($amount) => "<?= number_format($amount, 2) ?>");
        User::observe(UserObserver::class);
        Validator::extend('phone_kz', [PhoneRule::class, 'validate']);
    }
}

// bootstrap/providers.php
return [
    App\Providers\AppServiceProvider::class,
    App\Providers\PaymentServiceProvider::class,
];

Порядок выполнения: Laravel сначала вызывает register() у ВСЕХ провайдеров, затем boot() у ВСЕХ. Отсюда правило «в register — только биндинги, в boot — всё что использует другие сервисы».

1. HTTP-ядро — Illuminate\Foundation\Http\Kernel

Назначение: обрабатывает все веб-запросы, поступающие через public/index.php.

Точка входа: public/index.php вызывает метод handleRequest() у Application (Laravel 11+), который внутри дёргает Http\Kernel::handle($request).

// public/index.php (Laravel 11+)
$app = require __DIR__.'/../bootstrap/app.php';
$app->handleRequest(Request::capture());

2. Консольное ядро — Illuminate\Foundation\Console\Kernel

Назначение: обрабатывает все команды Artisan, запускаемые из терминала (php artisan migrate, php artisan queue:work, etc).

Точка входа: файл artisan в корне проекта вызывает метод handleCommand().

// artisan (Laravel 11+)
$app = require_once __DIR__.'/bootstrap/app.php';
$status = $app->handleCommand(new ArgvInput);
exit($status);

1. Запуск загрузчиков (Bootstrappers)

Перед обработкой запроса ядро выполняет серию подготовительных задач:

• Настройка обработки ошибок — регистрирует Whoops / Handler
• Настройка логирования — конфигурация каналов Monolog
• Определение окружения — читает APP_ENV из .env (local, production, testing)
• Загрузка всех сервис-провайдеров — самый важный шаг: они регистрируют и настраивают базу данных, очереди, валидацию, маршрутизацию, кеш и всё остальное

2. Управление промежуточным слоем (Middleware)

Ядро отвечает за то, чтобы запрос прошёл через стек middleware до того, как попадёт в контроллер. Эти middleware решают критически важные задачи, общие для всех или многих запросов:

• Чтение и запись HTTP-сессий (StartSession)
• Проверка CSRF-токена для защиты от межсайтовых подделок запросов (ValidateCsrfToken)
• Проверка, не находится ли приложение в режиме обслуживания (PreventRequestsDuringMaintenance)
• Trim пробелов, конвертация пустых строк в null, обработка CORS, доверие прокси, шифрование cookies

1. public/index.php — точка входа

Веб-сервер (nginx/Apache/built-in artisan serve) направляет любой URL в public/index.php. Этот файл загружает автозагрузчик Composer и bootstrap/app.php, который создаёт экземпляр Application (наследник IoC-контейнера).

2. Bootstrap: bootstrap/app.php

Конфигурируется ядро: список middleware, провайдеров, обработчик исключений, маршруты. В Laravel 11 это стало декларативной API в одном файле (раньше — отдельные классы в app/Http/Kernel.php).

3. Kernel handle

Http\Kernel::handle($request) прогоняет запрос через bootstrappers (загрузка .env, конфига, фасадов, провайдеров) — это происходит один раз в начале запроса.

4. Service Providers: register → boot

Все провайдеры сначала проходят register() (только биндинги в контейнер), потом boot() (всё остальное: маршруты, события, фасады, observers). Подробно — в KB_13.

5. Pipeline: глобальные middleware

Запрос идёт через очередь глобальных middleware (TrustProxies, HandleCors, PreventRequestsDuringMaintenance, ValidatePostSize, TrimStrings, ConvertEmptyStringsToNull). Каждый может либо передать запрос дальше, либо вернуть response самостоятельно.

6. Router: подбор маршрута

Router находит маршрут по методу + URL, прогоняет через middleware группы (web/api), затем route-specific middleware. Привязки моделей (route model binding) разрешаются на этом шаге.

7. Controller / Closure

Вызывается обработчик с разрешёнными зависимостями через контейнер. Возвращает Response или то, что фреймворк превратит в Response (массив → JSON, view → HTML, модель → JSON).

8. Pipeline в обратном порядке + terminate

Response поднимается обратно по middleware (теперь после $next($request)). После отправки клиенту вызываются terminate у middleware, поддерживающих такую фазу — здесь делается долгая работа (логирование, аналитика), не влияющая на время ответа.

Laravel 10 и ниже — явное создание ядра

Здесь виден полный цикл: получить ядро из контейнера, передать ему запрос, отправить ответ, вызвать terminate().

// public/index.php

$kernel = $app->make(Illuminate\Contracts\Http\Kernel::class);

$response = $kernel->handle(
    $request = Illuminate\Http\Request::capture()
);

$response->send();

$kernel->terminate($request, $response);

Laravel 11+ — цепочка вызовов через handleRequest()

С Laravel 11 код в index.php стал ещё более лаконичным. Вместо явного создания ядра и вызова handle() используется «цепочка» вызовов, которая заканчивается методом handleRequest().

// public/index.php

(require_once __DIR__.'/../bootstrap/app.php')
    ->handleRequest(Request::capture());

Метод handleRequest() внутри Application сам делает то же самое: получает Kernel из контейнера, передаёт запрос, отправляет ответ, вызывает terminate. Просто скрыто под красивую цепочку.

1. withRouting() — точки входа

->withRouting(
    web:      __DIR__.'/../routes/web.php',
    api:      __DIR__.'/../routes/api.php',
    commands: __DIR__.'/../routes/console.php',
    health:   '/up',                    // готовый эндпоинт для healthcheck
    apiPrefix: 'api/v1',
    then: function () {               // свои файлы роутов
        Route::middleware('web')
            ->prefix('admin')
            ->group(base_path('routes/admin.php'));
    },
)

2. withMiddleware() — глобальный конвейер запроса

->withMiddleware(function (Middleware $middleware) {
    $middleware->append(SetLocale::class);              // в конец глобального стека
    $middleware->prepend(TrustProxies::class);          // в начало
    $middleware->web(append: [EnsureProfileComplete::class]);  // в группу web
    $middleware->api(prepend: [ForceJsonResponse::class]);
    $middleware->alias(['admin' => AdminOnly::class]);  // короткое имя для роутов
    $middleware->remove(ValidateCsrfToken::class);      // выкинуть дефолтный
    $middleware->throttleApi('60,1');
    $middleware->trustProxies(at: '*');
    $middleware->validateCsrfTokens(except: ['webhooks/*']);
})

3. withExceptions() — что делать с ошибками

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->dontReport(BusinessRuleException::class);

    $exceptions->render(function (ModelNotFoundException $e, Request $request) {
        if ($request->expectsJson()) {
            return response()->json(['message' => 'Не найдено'], 404);
        }
    });

    $exceptions->report(function (PaymentFailed $e) {
        Sentry::captureException($e);
    });

    $exceptions->context(fn () => ['tenant_id' => tenant()?->id]);
})

4. withSchedule() — крон-задачи

->withSchedule(function (Schedule $schedule) {
    $schedule->command('reports:daily')->dailyAt('03:00');
})

Хотя чаще их пишут в routes/console.php.

5. withBindings() / withSingletons() — быстрые биндинги без провайдера

->withSingletons([
    PaymentGateway::class => StripeGateway::class,
])

Удобно для мелочи, но для чего-то серьёзного всё равно лучше провайдер — там есть boot() и логика группируется по смыслу.

register() — только привязки в контейнер

• Здесь запрещено использовать какие-либо другие сервисы (БД, кеш, конфиги, роутинг) — они ещё не загружены.
• Единственное, что можно — это $this->app->bind(...) или $this->app->singleton(...).
• Выполняется для всех провайдеров (в порядке их перечисления) прежде чем у какого-либо провайдера вызовется boot().

boot() — всё остальное

• Здесь уже зарегистрированы все провайдеры, поэтому можно использовать любые сервисы.
• Маршруты, события, Blade-директивы, observers, валидационные правила, макросы для Collection / Query Builder, gate policies.
• Выполняется после того, как у всех провайдеров отработал register().

Route model binding (implicit)

Route::get('/users/{user}', fn (User $user) => ...) — Laravel автоматически делает User::find($id) и кидает 404 если нет. По умолчанию ищет по PK; для другого ключа — $user:slug или getRouteKeyName() на модели.

Explicit binding

В RouteServiceProvider::boot: Route::bind('user', fn ($value) => User::where(...)->firstOrFail()) — кастомная логика разрешения. Полезно для мультитенантности, scope'ов.

Scoped bindings

Route::get('/users/{user}/posts/{post:slug}', ...)->scopeBindings() — Post ищется в контексте User (через relation). Гарантирует, что /users/1/posts/foo не вернёт пост, принадлежащий другому пользователю.

Middleware на маршруте/группе

Маршрут получает middleware из своей группы (web/api), плюс заявленные через ->middleware('auth'). Порядок: глобальные → групповые → маршрутные. Параметры middleware: auth:sanctum, throttle:60,1.

Route caching

php artisan route:cache компилирует все маршруты в единый PHP-файл bootstrap/cache/routes-v7.php — кратно ускоряет startup. Сброс — route:clear. Разбор — в подразделе «Кеширование маршрутов» ниже.

Signed routes

URL::signedRoute('verify', ['user' => $id]) — URL с подписью, защищающей от подмены параметров. Используется для подтверждения email, magic-link login и пр. Middleware signed проверяет.

Implicit Binding (неявная привязка)

Laravel сам догадывается, как найти модель по ID в URL. Указываешь в параметре роута имя переменной, совпадающее с именем модели, и Laravel делает Model::find($id). Если не находит — автоматически 404.

Route::get('/users/{user}', function (User $user) {
    return $user;   // Laravel сам вызывает User::find($user)
});

По умолчанию ищет по первичному ключу (id). Чтобы искать по другому полю (например, slug) — либо в модели определить getRouteKeyName(), либо передать в параметре {user:slug}.

// Способ 1: параметр в URL
Route::get('/users/{user:slug}', fn (User $user) => $user);

// Способ 2: на уровне модели — глобально
class User extends Model
{
    public function getRouteKeyName(): string
    {
        return 'slug';
    }
}

Explicit Binding (явная привязка)

Ты сам говоришь, как именно доставать модель. Нужно, если логика сложнее чем просто find(): мультитенантность, скоуп по владельцу, дополнительные условия.

// В RouteServiceProvider::boot() или bootstrap/app.php (L11)
Route::bind('user', function ($value) {
    return User::where('tenant_id', auth()->id())
               ->where('id', $value)
               ->firstOrFail();
});

// Теперь при каждом /users/{user} — используется твоя логика
Route::get('/users/{user}', fn (User $user) => $user);
// Юзер чужого tenant → 404

Scoped Bindings (привязка с контекстом)

Частный случай implicit binding, но с дополнительным условием: модель ищется в рамках отношения с другой моделью. Пример: у пользователя есть посты. URL /users/{user}/posts/{post}. Без scoped binding Laravel найдёт пост по slug глобально, даже если он не принадлежит этому пользователю.

Route::get('/users/{user}/posts/{post:slug}', function (User $user, Post $post) {
    return $post;
})->scopeBindings();
// С scopeBindings() Laravel строит запрос через отношение $user->posts():
// Post::where('user_id', $user->id)->where('slug', $post)->firstOrFail()
// Если поста с таким slug у данного пользователя нет — 404

Closure Routes (замыкание вместо контроллера)

Closure — анонимная функция, которая прямо в роуте обрабатывает запрос. Удобно для быстрых тестов, health-check эндпоинтов, роутов на 1 строчку.

Route::get('/hello', function () {
    return 'Hello, world!';
});

Invokable Classes (инвокабельные классы)

Классы с единственным методом __invoke(). Используются как обработчики роута вместо контроллеров с несколькими методами. Выглядит чище для простых действий (Single Action Controllers).

// app/Http/Controllers/ShowProfile.php
class ShowProfile
{
    public function __invoke($id)
    {
        return view('profile', ['user' => User::findOrFail($id)]);
    }
}

// routes/web.php
Route::get('/profile/{id}', ShowProfile::class);
// Laravel сам создаст экземпляр и вызовет __invoke()
// Кешируется при route:cache без сериализации — в кеш ложится имя класса

Signed Routes (подписанные маршруты)

URL с добавленной криптографической подписью (хеш) — защищает параметры от подмены. Используются для подтверждения email, ссылок для сброса пароля, magic login.

use Illuminate\Support\Facades\URL;

// Создаёшь подписанный URL
$url = URL::signedRoute('verify', ['user' => 1]);
// https://yourapp.com/verify?user=1&signature=abc123...

// Временный (с истечением) — предпочтительно для magic-link
$url = URL::temporarySignedRoute('verify', now()->addMinutes(15), ['user' => 1]);

// В роуте применяешь middleware signed
Route::get('/verify', function (Request $request) {
    // Подпись валидна, параметры не подменены
})->name('verify')->middleware('signed');
// Если кто-то изменит user=1 на user=2 — подпись невалидна, middleware вернёт 403

Explicit Binding — «как искать»

Регистрируется один раз и применяется ко всем маршрутам, где встречается параметр с таким именем: и /users/{user}, и /admin/users/{user}, и /api/users/{user}.

// AppServiceProvider::boot()
Route::bind('user', function ($value) {
    return User::where('tenant_id', tenant()->id)
               ->where('id', $value)
               ->firstOrFail();
});

Ключевое: запрос пишешь ты целиком. Laravel не делает find(), он просто вызывает твой колбэк и берёт результат.

Scoped Bindings — «искать в контексте родителя»

Логика поиска остаётся стандартной, добавляется ограничение: дочерняя модель достаётся через отношение родительской.

Route::get('/users/{user}/posts/{post}', function (User $user, Post $post) {
    return $post;
})->scopeBindings();

// Laravel строит запрос через отношение, имя угадывает по имени параметра:
// $user->posts()->where('id', $value)->firstOrFail()

Ключевое: ты не пишешь запрос, а сообщаешь Laravel: «ищи пост среди постов этого пользователя». Имя отношения выводится из имени параметра во множественном числе — {post} → $user->posts().

Управление скоупом на группе и его отключение

// Включить для всей группы маршрутов
Route::scopeBindings()->group(function () {
    Route::get('/users/{user}/posts/{post}', [PostController::class, 'show']);
    Route::get('/users/{user}/orders/{order}', [OrderController::class, 'show']);
});

// Принудительно отключить, даже при кастомном ключе
Route::get('/users/{user}/posts/{post:slug}', fn (User $user, Post $post) => $post)
    ->withoutScopedBindings();

Включать скоуп на группе надёжнее, чем на каждом маршруте: забыть один вызов в списке из двадцати вложенных ресурсов — вопрос времени.

Третий способ: переопределение на модели

Если логика поиска — свойство самой модели, а не маршрута, её можно задать прямо в модели. Это работает и там, где Route::bind() был бы слишком грубым (он перехватывает параметр во всём приложении).

class Post extends Model
{
    // Обычный implicit binding
    public function resolveRouteBinding($value, $field = null)
    {
        return $this->where($field ?? 'id', $value)
                    ->where('status', 'published')
                    ->firstOrFail();
    }

    // Вызывается вместо предыдущего, когда действует scoped binding
    public function resolveChildRouteBinding($childType, $value, $field)
    {
        return parent::resolveChildRouteBinding($childType, $value, $field);
    }
}

Что происходит без кеша и с ним

Команды

# Собрать кеш маршрутов
php artisan route:cache

# Сбросить кеш
php artisan route:clear

# Собрать сразу всё: config + events + routes + views
php artisan optimize

# Сбросить всё разом
php artisan optimize:clear

# Список маршрутов — работает и при активном кеше
php artisan route:list

optimize — это не отдельная магия, а последовательный запуск config:cache, event:cache, route:cache и view:cache. Стандартный шаг продакшен-деплоя.

Closure-маршруты и кеш

Правило «замыкания нельзя закешировать» разошлось по статьям и до сих пор встречается в подготовительных материалах. В актуальных версиях Laravel оно неверно: замыкание сериализуется через пакет laravel/serializable-closure.

// Illuminate\Routing\Route::prepareForSerialization()
if ($this->action['uses'] instanceof Closure) {
    $this->action['uses'] = serialize(
        SerializableClosure::unsigned($this->action['uses'])
    );
}

Раньше на этом месте бросалось исключение LogicException: Unable to prepare route [...] for serialization. Uses Closure. — сейчас его в коде нет. Держать логику в контроллерах по-прежнему стоит, но ради читаемости и тестируемости, а не из-за кеша.

Подводные камни

Что именно подписывается

Всё сводится к одной строке в UrlGenerator::hasCorrectSignature():

hash_hmac('sha256', $original, $key)
// $original = полный URL с query-строкой, но БЕЗ параметра signature
// $key      = APP_KEY приложения
// сравнение — через hash_equals(), защита от timing-атак

При генерации параметры проходят через ksort() — порядок в подписанной ссылке всегда алфавитный, поэтому подпись воспроизводима. Срок жизни — это не отдельный механизм, а обычный query-параметр expires с unix-таймстампом, который тоже попадает под подпись.

// Illuminate\Routing\Exceptions\InvalidSignatureException
parent::__construct(403, 'Invalid signature.');

Абсолютная и относительная подпись

По умолчанию подписывается абсолютный URL — вместе со схемой и доменом. Значит подпись развалится, если ссылка сгенерирована на одном хосте, а проверяется на другом: воркер с другим APP_URL, балансировщик, подменяющий схему на http, смена домена.

// Относительная подпись — домен и схема в хеш не входят
$url = URL::signedRoute('verify', ['user' => 1], null, false);

// И проверять её нужно соответствующим вариантом middleware
Route::get('/verify', VerifyController::class)
    ->middleware('signed:relative');

// Вручную:
$request->hasValidRelativeSignature();

Несовпадение режимов — типичная причина «у меня локально работает, а на проде 403».

Лишние query-параметры ломают подпись

Хеш считается от всей query-строки. Почтовые сервисы и трекеры любят дописывать своё: utm_source, параметры Outlook SafeLinks, метки рассылок. Любая такая добавка делает подпись невалидной.

// Игнорировать конкретные параметры при проверке
use Illuminate\Routing\Middleware\ValidateSignature;

Route::get('/verify', VerifyController::class)
    ->middleware(ValidateSignature::absolute(['utm_source', 'utm_campaign']));

// Относительный вариант с тем же игнором
ValidateSignature::relative(['utm_source']);

Игнорируемые параметры выбрасываются из строки до подсчёта хеша. Добавлять в этот список стоит только то, что не влияет на логику: подпись их больше не защищает.

Ротация APP_KEY

Подпись завязана на APP_KEY. Смена ключа мгновенно обесценивает все выданные ссылки — незавершённые верификации email и висящие magic-link'и перестанут открываться. Поэтому проверка идёт по списку ключей:

// .env
APP_KEY=base64:новый...
APP_PREVIOUS_KEYS=base64:старый...

// Генерация — всегда текущим ключом ($key[0])
// Проверка — перебором по всем ключам, пока один не совпадёт

Тестируемость

PlaceOrderAction тестируется отдельно от HTTP — просто $action->handle($data) с моками зависимостей. Никаких Request/Response.

Переиспользование

Один PlaceOrderAction можно вызывать из: контроллера, Artisan-команды, другого Action, Job, Console kernel. Логика не привязана к HTTP.

Асинхронность

Тяжёлые побочные эффекты (email) — через ShouldQueue listener. Ответ пользователю моментальный.

Подмена платёжного шлюза

Смена Stripe → YooKassa = одна строка биндинга в провайдере. Тесты — FakePaymentGateway без реальных запросов.

Global

Применяются ко всем запросам. Регистрируются в bootstrap/app.php (Laravel 11+) или app/Http/Kernel.php::$middleware. Типичные: TrustProxies, HandleCors, TrimStrings.

Group (web / api)

Применяются ко всем маршрутам группы. web: session, CSRF, cookies. api: throttle, без session. Группы кастомизируются через $middlewareGroups.

Route-specific

Через ->middleware(['auth', 'verified']) или alias ->middleware('auth:sanctum'). Aliases объявляются в $middlewareAliases.

Параметризованный middleware

throttle:60,1 — middleware ThrottleRequests с параметрами 60 запросов в 1 минуту. Параметры приходят в handle($request, $next, ...$params).

terminate

Метод вызывается после отправки response клиенту. Здесь дорогая работа (логи в БД, отправка метрик), не влияющая на TTFB. Работает только под FPM с fastcgi_finish_request.