Архивы Laravel - mcodex https://mcodex.ru/category/laravel/ Короткие статьи об основных понятиях, терминах и концепциях веб-разработки Sun, 09 Aug 2026 20:15:30 +0000 ru-RU hourly 1 https://wordpress.org/?v=7.0.3 https://mcodex.ru/wp-content/uploads/2025/11/cropped-favicon_650-32x32.png Архивы Laravel - mcodex https://mcodex.ru/category/laravel/ 32 32 Разбираемся с сервис-контейнером в Laravel. https://mcodex.ru/laravel-service-container/ Sun, 09 Aug 2026 15:14:12 +0000 https://mcodex.ru/?p=405 Содержание Keynotes Почти каждый, кто пишет на Laravel, хотя бы раз слышал: «ну это же контейнер разрешает зависимости». Звучит солидно, но за этой фразой у многих пустота. Давайте её заполним. Мы пойдём от проблемы к решению: сначала посмотрим, какую боль контейнер лечит, потом разберём, как он устроен внутри, а в конце напишем свой мини-контейнер строк ... Читать далее

Сообщение Разбираемся с сервис-контейнером в Laravel. появились сначала на mcodex.

]]> Содержание
  1. Сначала главное: что такое контейнер и провайдер
  2. Проблема, которой не видно на маленьких проектах
  3. Первое лекарство: внедрение зависимостей
  4. Проблема, которую породило лекарство
  5. Что такое контейнер
  6. Автоматическое разрешение зависимостей
  7. Привязки
  8. Контекстные привязки и атрибуты
  9. Как получить объект из контейнера
  10. Сервис-провайдеры
  11. Фасады и вспомогательные функции
  12. Дополнительные возможности контейнера
  13. Тестирование
  14. Типичные ошибки
  15. Свой мини-контейнер
  16. Итог

Keynotes

  • Контейнер (service container) отвечает за создание объектов и их зависимостей.
  • Внедрение зависимостей (dependency injection, DI) означает, что класс получает нужные ему объекты извне, а не создаёт их сам.
  • Автоматическое разрешение зависимостей (autowiring) — контейнер читает типы параметров конструктора и сам создаёт нужные объекты, рекурсивно повторяя это для их зависимостей.
  • Привязка (binding) нужна, когда контейнеру недостаточно информации: например, когда зависимость является интерфейсом или требует конкретных значений.
  • Сервис-провайдер (service provider) — класс, который Laravel запускает при старте приложения; в нём регистрируют такие привязки и выполняют начальную настройку.
  • Контекстные атрибуты (contextual attributes) (Laravel 11+) позволяют описать то же правило прямо у параметра конструктора, не заводя привязку в провайдере.
  • В большинстве обычных классов достаточно написать тип зависимости в конструкторе. Не нужно регистрировать каждый класс вручную.
  • Контейнер — это инструмент сборки объектов. Он не заменяет внедрение зависимостей и не является обязательной частью самого принципа DI.

Почти каждый, кто пишет на Laravel, хотя бы раз слышал: «ну это же контейнер разрешает зависимости». Звучит солидно, но за этой фразой у многих пустота. Давайте её заполним.

Мы пойдём от проблемы к решению: сначала посмотрим, какую боль контейнер лечит, потом разберём, как он устроен внутри, а в конце напишем свой мини-контейнер строк на семьдесят, чтобы магия окончательно перестала быть магией.

1. Сначала главное: что такое контейнер и провайдер

Прежде чем разбирать код, полезно сразу разделить две вещи, которые в Laravel часто упоминают вместе.

Контейнер — это объект, который умеет создавать другие объекты и подставлять им необходимые зависимости.

Сервис-провайдер — это класс, который Laravel запускает при старте приложения, до обработки запроса. Именно в нём приложение объясняет контейнеру, как именно создавать некоторые объекты.

Например, контейнер и без всякой настройки понимает, как создать:

class OrderService
{
    public function __construct(
        private OrderRepository $orders,
    ) {}
}

Если OrderRepository можно создать через new (то есть это не интерфейс и не абстрактный класс), параметры его конструктора тоже объявлены типами классов, Laravel соберёт всю цепочку сам.

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

Работает это так.
Есть точки входа, которые Laravel создаёт через контейнер без вашего участия: контроллеры, посредники, консольные команды, слушатели событий, методы handle() у заданий очереди. Дальше цепочка продолжается сама: контроллер объявил в конструкторе параметер типа OrderService — значит, инстанс OrderService тоже создаёт контейнер, а раз так, подставится и его OrderRepository.
Глубина не ограничена и лежать эти классы могут где угодно, например, в созданной разработчиком папке app/Services.

Рвётся цепочка ровно в одном случае — когда объект создаёте вы сами:

// Контейнер не участвует: все аргументы нужно передать руками
$service = new OrderService(new OrderRepository());

// Просим контейнер — зависимости подставятся сами
$service = app(OrderService::class);

Отсюда и практическая рекоммендация: для классов с зависимостями не пишите new, а объявляйте тип в конструкторе там, куда объект в итоге попадёт.

Но если класс требует строку:

class SmsSender
{
    public function __construct(
        private string $apiKey,
    ) {}
}

контейнер не знает, какую именно строку нужно передать. В этом случае мы должны зарегистрировать привязку в сервис-провайдере:

$this->app->bind(SmsSender::class, function () {
    return new SmsSender(config('services.sms.key'));
});

То есть схема очень простая:

сервис-провайдер регистрирует правила → контейнер использует эти правила → приложение получает готовые объекты.

Провайдер при этом не является самим контейнером и не создаёт зависимости вместо него. Его задача — настроить приложение и зарегистрировать в контейнере нужные правила.

Теперь посмотрим, зачем вообще понадобился такой механизм.

Четыре понятия, которые важно не смешивать

Их легко запутать, поэтому зафиксируем:

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

Именно поэтому контейнер не стоит воспринимать как «магическую замену new». Его задача — централизовать правила создания объектов там, где это действительно необходимо.

2. Проблема, которой не видно на маленьких проектах

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

class SmsSender
{
    public function send(string $phone, string $text): void
    {
        // обращение к внешнему шлюзу
    }
}

class OrderService
{
    public function confirm(Order $order): void
    {
        $sender = new SmsSender();
        $sender->send($order->user->phone, 'Заказ подтверждён');
    }
}

Работает. Пока не начнёшь задавать вопросы.

Вопрос первый. У SmsSender появился конструктор: ему нужен ключ доступа и адрес шлюза.

class SmsSender
{
    public function __construct(
        private string $apiKey,
        private string $endpoint,
    ) {}
}

Теперь OrderService обязан знать про ключи и адреса. Это не его дело: он про заказы, а не про настройки внешнего шлюза. Но ему придётся, потому что он сам создаёт объект.

Вопрос второй. Таких мест в коде не одно, а тридцать. Ключ поменялся — правим тридцать файлов.

Вопрос третий. Пришёл бизнес и сказал: в Казахстане шлём не через SMS, а через мессенджер. Значит, нужен другой класс. И теперь по всему коду расползаются if.

Вопрос четвёртый, самый болезненный. Как это протестировать? В тесте OrderService::confirm() реально уйдёт в интернет и потратит деньги. Подменить нечем: объект создаётся жёстко, внутри метода.

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

3. Первое лекарство: внедрение зависимостей

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

class OrderService
{
    public function __construct(
        private SmsSender $sender,
    ) {}

    public function confirm(Order $order): void
    {
        $this->sender->send($order->user->phone, 'Заказ подтверждён');
    }
}

Вот и всё. Это и называется внедрением зависимостей (dependency injection). Никакой философии: объект объявляет, что ему нужно для работы, а кто и как это соберёт — не его забота.

Сделаем ещё шаг и заменим конкретный класс на договорённость (интерфейс):

interface NotificationSender
{
    public function send(string $phone, string $text): void;
}

class OrderService
{
    public function __construct(
        private NotificationSender $sender,
    ) {}
}

Теперь OrderService вообще не знает, кто там за интерфейсом: SMS, мессенджер или заглушка в тесте. Он знает только, что у объекта есть метод send(). Связанность резко упала.

Но появилась новая проблема.

4. Проблема, которую породило лекарство

Раньше мы писали new OrderService(). Теперь так нельзя:

$service = new OrderService(
    new SmsSender(
        config('services.sms.key'),
        config('services.sms.endpoint'),
    )
);

А если у SmsSender есть свои зависимости, а у них — свои, то сборка одного объекта превращается в трёхэтажную конструкцию. И такую конструкцию придётся повторять в каждом контроллере, команде, обработчике очереди.

Мы просто перенесли боль из одного места в другое.

Значит, нужен кто-то, кто возьмёт на себя всю работу по сборке объектов. Один на всё приложение. Кто-то, кому можно сказать: «дай мне OrderService«, а он сам разберётся, что для этого нужно создать и в каком порядке.

Этот «кто-то» и есть контейнер служб (service container).

5. Что такое контейнер

Контейнер — это объект, который умеет создавать другие объекты и разрешать их зависимости.

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

В Laravel контейнер является объектом приложения (класс Illuminate\Foundation\Application, который наследуется от Illuminate\Container\Container). Получить его можно с помощью глобальной функции app().

Самое главное: вы почти никогда не обращаетесь к контейнеру напрямую. Laravel сам создаёт через него контроллеры, консольные команды, слушатели событий, посредники. Именно поэтому достаточно написать тип в конструкторе контроллера — и объект окажется там сам.

Отдельно стоит сказать про задания очередей (Job): их вы создаёте сами (new SendSms($order) и dispatch()), а между постановкой в очередь и выполнением объект сериализуется и десериализуется. Конструктор задания через контейнер не проходит. Зато метод handle() вызывается через контейнер, поэтому зависимости удобно объявлять именно в нём. Но об этом ниже, в разделе про внедрение в методы.

6. Автоматическое разрешение: где именно происходит «магия»

Пишем:

class OrderController extends Controller
{
    public function __construct(
        private OrderService $orders,
    ) {}
}

Мы нигде не сказали контейнеру, что такое OrderService. Откуда он взялся?

Пошагово контейнер делает следующее:

  1. Смотрит на строку App\Services\OrderService. Проверяет, нет ли уже созданного ранее объекта . Нет.
  2. Раз объекта нет, но класс существует — попробуем создать его сами.
  3. Через рефлексию (ReflectionClass) заглядывает внутрь класса и достаёт конструктор.
  4. Перебирает параметры конструктора и смотрит на их типы.
  5. Тип NotificationSender — не скалярный, значит это чья-то зависимость. Рекурсивно повторяем весь алгоритм уже для неё.
  6. Когда все параметры собраны, вызывает new OrderService(...$параметры).

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

Этот механизм называют автоматическим связыванием (autowiring). Он требует выполнения хотя бы одного из условий для каждого параметра:

  • параметр объявлен типом класса, и этот тип разрешим: либо это конкретный создаваемый класс, либо интерфейс, для которого явно указана реализация;
  • у параметра есть значение по умолчанию. Тогда контейнер просто возьмёт его и не будет ничего собирать. Это касается и скаляров (string $prefix = 'sms'), и классов (?LoggerInterface $logger = null).

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

Для интерфейса или абстрактного класса без привязки:

Target [App\Contracts\NotificationSender] is not instantiable
  while building [App\Http\Controllers\OrderController].

Для обязательного скаляра:

Unresolvable dependency resolving [Parameter #0 [ <required> string $apiKey ]]
  in class App\Services\SmsSender

Оба исключения — это Illuminate\Contracts\Container\BindingResolutionException. Разница в тексте мелочь, но именно по нему вы будете искать причину, поэтому полезно различать: первое означает «не знаю, какую реализацию взять», второе — «не знаю, какое значение подставить». И это правильное поведение: угадывать за вас контейнер не должен.

7. Привязки: объясняем контейнеру то, чего он не угадает

Инструкции контейнеру мы указываем в сервис-провайдере (service provider). Обычно это класс App\Providers\AppServiceProvider, метод register().

7.1. bind(). Рецепт создания экземпляра класса.

public function register(): void
{
    $this->app->bind(SmsSender::class, function (Application $app) {
        return new SmsSender(
            config('services.sms.key'),
            config('services.sms.endpoint'),
        );
    });
}

Читается так: «когда у тебя попросят SmsSender, не пытайся собрать его сам, а выполни вот эту функцию».

Замыкание получает два аргумента: сам контейнер и массив параметров, переданных при разрешении (о них в разделе про makeWith). Полная сигнатура выглядит так:

$this->app->bind(SmsSender::class, function (Application $app, array $parameters = []) {
    // внутри доступен $app->make(...) для остальных зависимостей
});

Второй аргумент нужен редко, поэтому обычно пишут только первый.

Важная деталь: bind создаёт новый объект при каждом разрешении. Речь именно про каждый вызов make()/app(), а не про HTTP-запрос: попросили пять раз внутри одного запроса — получили пять разных объектов.

7.2. Привязка интерфейса к реализации.

Ради этого контейнеры и придумывали:

$this->app->bind(NotificationSender::class, SmsSender::class);

«Когда кто-то просит интерфейс — давай ему вот этот класс».
Теперь автоматическое связывание снова работает: контейнер, увидев NotificationSender в конструкторе, знает, чем его заменить.

Хотите переключиться на мессенджер? Меняете одну строку в сервис-провайдере, а код приложения не трогаете вообще.

Можно и по условию:

$this->app->bind(NotificationSender::class, function (Application $app) {
    return config('services.default_channel') === 'telegram'
        ? $app->make(TelegramSender::class)
        : $app->make(SmsSender::class);
});

7.3. singleton(). Один экземпляр на жизненный цикл контейнера.

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

Первый вызов создаёт объект, последующие обращения к контейнеру возвращают тот же экземпляр. В обычном PHP-приложении с коротким жизненным циклом процесса это обычно означает один экземпляр в рамках текущего запроса. В долгоживущих процессах, например при использовании Laravel Octane или обработчиков очередей, такой объект может жить намного дольше. Поэтому состояние внутри singleton нужно хранить очень осторожно.

7.4. instance(). Использовать готовый объект.

$client = new HttpClient(['timeout' => 5]);
$this->app->instance(HttpClient::class, $client);

Здесь мы не даём рецепт, а сразу передаем готовый объект.

7.5. scoped(). Один экземпляр на жизненный цикл запроса.

$this->app->scoped(RequestContext::class, function () {
    return new RequestContext();
});

Ведёт себя как singleton, но экземпляр привязан к текущему жизненному циклу. В долгоживущих процессах Laravel очищает такие экземпляры между отдельными запросами или заданиями. Это особенно важно для Laravel Octane и очередей: состояние одного запроса или задания не должно переходить к следующему.

7.6. singletonIf() и bindIf()

Регистрируют привязку, только если такой ещё нет. Полезно в пакетах: не перетираем то, что пользователь настроил у себя.

8. Контекстные привязки: одному одно, другому другое.

Бывает, что один и тот же интерфейс должен разрешаться по-разному в зависимости от того, кто просит. Классический пример — хранилище файлов:

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

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

Тем же способом можно подставлять скалярные значения, которые нельзя разрешить автоматически:

$this->app->when(SmsSender::class)
    ->needs('$apiKey')
    ->give(fn () => config('services.sms.key'));

Обратите внимание на знак доллара: здесь мы указываем не тип, а конкретное имя параметра конструктора.

Если правило одинаковое для нескольких классов, when() принимает массив:

$this->app->when([VideoController::class, UploadController::class])
    ->needs(Filesystem::class)
    ->give(fn () => Storage::disk('s3'));

А для самого частого случая — подстановки значения из конфига — есть сокращение:

$this->app->when(SmsSender::class)
    ->needs('$apiKey')
    ->giveConfig('services.sms.key');

Аналогично giveTagged('reports') отдаёт группу объектов, помеченных меткой (о метках — в разделе 11).

8.1. Контекстные атрибуты: то же самое, но без провайдера

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

use Illuminate\Container\Attributes\Config;

class SmsSender
{
    public function __construct(
        #[Config('services.sms.key')] private string $apiKey,
        #[Config('services.sms.endpoint')] private string $endpoint,
    ) {}
}

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

use Illuminate\Container\Attributes\Storage;
use Illuminate\Contracts\Filesystem\Filesystem;

class PhotoController extends Controller
{
    public function __construct(
        #[Storage('public')] private Filesystem $disk,
    ) {}
}

Кроме Config и Storage в коробке есть Auth, Cache, Context, DB, Give, Log, RequestAttribute, RouteParameter и Tag. Отдельно стоит CurrentUser — он внедряет текущего аутентифицированного пользователя, в том числе прямо в замыкание маршрута:

use App\Models\User;
use Illuminate\Container\Attributes\CurrentUser;

Route::get('/user', function (#[CurrentUser] User $user) {
    return $user;
})->middleware('auth');

Свой атрибут делается реализацией контракта Illuminate\Contracts\Container\ContextualAttribute: контейнер вызовет метод resolve() и подставит то, что тот вернёт.

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

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

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

9. Как достать объект из контейнера

Способов несколько, и они не равнозначны по стилю.

// Предпочтительный способ: просто объявите тип, Laravel подставит сам
public function __construct(private OrderService $orders) {}

// Явное создание
$orders = app(OrderService::class);
$orders = App::make(OrderService::class);
$orders = resolve(OrderService::class);

// С передачей части аргументов вручную
$sender = app()->makeWith(SmsSender::class, ['apiKey' => 'test-key']);

app() и resolve() — вспомогательные функции для получения объекта из контейнера. Непосредственно у самого контейнера для этого используется метод make().

Про makeWith важно знать две вещи. Во-первых, переданные значения доходят только до сборки класса или до замыкания-рецепта (тот самый второй аргумент из раздела 6.1) и сопоставляются по имени параметра. Во-вторых, результат такого вызова не кэшируется, даже если привязка зарегистрирована как singleton: контейнер считает разрешение с параметрами частным случаем и общий экземпляр не сохраняет и не подменяет. Это ровно то поведение, которое нужно, но оно удивляет, если ждать обратного.

Контейнер также реализует стандарт PSR-11 (Psr\Container\ContainerInterface), то есть у него есть методы get() и has(). Пригодится, если библиотека умеет работать с любым PSR-совместимым контейнером. Разница с make() в поведении при ошибке: get() бросает исключения из стандарта PSR, а не BindingResolutionException.

Контейнер умеет разрешать зависимости не только в конструкторах, но и в методах:

public function store(Request $request, OrderService $orders, string $id)
{
    // $request и $orders придут из контейнера,
    // $id — из параметров маршрута
}

Laravel умеет внедрять зависимости в методы, которые фреймворк вызывает через контейнер. Например, зависимости передаются в методы контроллеров, а также в методы вроде handle() у заданий очереди и слушателей событий — то есть там, где объект запускает сам фреймворк. Параметры маршрута при этом сопоставляются по имени, а зависимости — по типу, поэтому порядок аргументов в сигнатуре роли не играет.

Тот же механизм доступен вручную через call():

app()->call([$report, 'generate']);
app()->call(function (OrderService $orders) {
    // ...
});

10. Где живут настройки: сервис-провайдеры

Сервис-провайдер — это класс, через который Laravel настраивает часть приложения. В нём чаще всего встречаются два метода: register() и boot(). Они нужны для разных задач.

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Только привязки. Больше ничего.
        $this->app->bind(NotificationSender::class, SmsSender::class);
    }

    public function boot(): void
    {
        // Здесь уже можно пользоваться другими службами
        View::share('appVersion', config('app.version'));
    }
}

Правило, которое стоит запомнить: в register() мы только записываем рецепты, но не готовим по ним. Причина простая: Laravel сначала вызывает register() у всех сервис-провайдеров и только потом boot() у всех. Если в register() вы попробуете достать из контейнера что-то, что регистрируется сервис-провайдером ниже по списку, вы получите ошибку или, что хуже, объект, собранный не до конца.

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

10.1 Откуда берутся провайдеры

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

Провайдеры самого фреймворка. Маршрутизация, кэш, очереди, сессии — всё это регистрируется провайдерами Laravel. Они загружаются автоматически, и трогать их не нужно.

Провайдеры пакетов. Начиная с Laravel 5.5 работает автообнаружение: пакет объявляет свой провайдер в composer.json (секция extra.laravel.providers), и после composer require он подключается сам. Прописывать его куда-либо вручную не требуется.

Ваши собственные. В свежем проекте уже есть один — App\Providers\AppServiceProvider. Для подавляющего большинства приложений его достаточно: все привязки живут в его register(), вся начальная настройка — в boot(). Отдельный провайдер имеет смысл заводить, когда вокруг одной подсистемы набирается заметный кусок настройки (платежи, интеграция с внешним API) и его хочется вынести, либо когда провайдер нужен отложенным, либо когда вы пишете пакет.

Если такой момент настал, файл не создают руками:

php artisan make:provider PaymentServiceProvider

В Laravel 11 и новее команда сама допишет класс в bootstrap/providers.php. В более старых версиях его нужно добавить в массив providers файла config/app.php.

10.2 Отложенные сервис-провайдеры

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

lass SmsServiceProvider extends ServiceProvider implements DeferrableProvider
{
    public function register(): void
    {
        $this->app->singleton(SmsSender::class, fn () => new SmsSender(/* ... */));
    }

    public function provides(): array
    {
        return [SmsSender::class];
    }
}
```

Laravel запомнит, что этот провайдер предоставляет SmsSender, и сможет загрузить провайдер только тогда, когда такая служба действительно понадобится. Соответствие «служба → провайдер» кэшируется в bootstrap/cache/services.php, поэтому после изменения provides() кэш стоит сбросить (php artisan clear-compiled).

11. Фасады и вспомогательные функции — это тоже контейнер

Многих смущает конструкция вида Cache::get('key'). Выглядит как статический вызов, но get() там точно не статический метод.

Внутри всё устроено предельно просто. Фасад — это класс, у которого определён магический метод __callStatic(). Он достаёт из контейнера настоящий объект по строковому ключу и перенаправляет вызов ему:

class Cache extends Facade
{
    protected static function getFacadeAccessor(): string
    {
        return 'cache';
    }
}

То есть Cache::get('key') по смыслу можно представить примерно как обращение к объекту, который контейнер хранит под ключом cache: app('cache')->get('key'). Фасад скрывает получение этого объекта за статическим синтаксисом.

Отсюда же растут ноги у удобного тестирования: Cache::shouldReceive(...) просто подменяет объект в контейнере на заглушку, а весь остальной код продолжает работать, ничего не заметив.

12. Приёмы, до которых доходят не сразу

12.1 Метки (tags)

Когда нужно получить целую группу объектов:

$this->app->bind(PdfReport::class, fn () => new PdfReport());
$this->app->bind(ExcelReport::class, fn () => new ExcelReport());

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

// Позже
foreach ($this->app->tagged('reports') as $report) {
    $report->generate();
}

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

Одна ловушка: tagged() возвращает не массив, а Illuminate\Container\RewindableGenerator. В foreach он ведёт себя как обычная коллекция и объекты создаются лениво, но обратиться по индексу или прогнать через array_map() не получится. Если нужен именно массив — iterator_to_array($this->app->tagged('reports')).

12.2 Расширение уже созданного (extend)

Позволяет вклиниться и обернуть объект, не переписывая исходную привязку:

$this->app->extend(NotificationSender::class, function ($sender, $app) {
    return new LoggingSenderDecorator($sender, $app->make(LoggerInterface::class));
});

Особенно ценно, когда нужно доработать поведение стороннего пакета.

12.3 События контейнера

$this->app->resolving(SmsSender::class, function ($sender, $app) {
    // выполнится при фактической сборке SmsSender
});

$this->app->afterResolving(...);

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

Тонкость, которая обычно всплывает уже на отладке: коллбэк срабатывает при сборке объекта, а не при каждом обращении к контейнеру. Если служба зарегистрирована через singleton или instance, то со второго раза make() вернёт готовый экземпляр из кэша, не дойдя до коллбэков. Для bind объект собирается каждый раз, поэтому там коллбэк отработает при каждом разрешении.

13. Тестирование: ради этого тоже всё затевалось

Вернёмся к самой первой проблеме. Как теперь протестировать OrderService, не тратя деньги на реальные SMS?

Способ первый, без всякого Laravel:

$fakeSender = new class implements NotificationSender {
    public array $sent = [];

    public function send(string $phone, string $text): void
    {
        $this->sent[] = [$phone, $text];
    }
};

$service = new OrderService($fakeSender);
$service->confirm($order);

$this->assertCount(1, $fakeSender->sent);

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

Способ второй, через подмену в контейнере:

$this->mock(NotificationSender::class, function ($mock) {
    $mock->shouldReceive('send')->once();
});

$this->post('/orders/1/confirm');

Теперь весь код приложения, который просит NotificationSender, получит заглушку. Ни строчки в самом приложении менять не пришлось.

Есть ещё $this->swap(Интерфейс::class, $объект) и $this->instance(...) — те же идеи в разных обёртках.

14. Грабли, на которые наступают все

Синглтон с состоянием. Если в объекте, зарегистрированном как singleton, вы накапливаете данные, при обычной работе это относительно безопасно (процесс живёт один запрос). Но под Octane или в долгоживущем обработчике очереди процесс обслуживает тысячи запросов подряд, и данные одного пользователя утекут к другому. Для состояния, привязанного к запросу, используйте scoped, а не singleton.

Внедрение запроса в синглтон. Классическая ловушка: объект-синглтон принимает Illuminate\Http\Request в конструкторе. Экземпляр создаётся один раз, вместе с ним один раз разрешается и запрос — дальше объект будет вечно держать самый первый. В обычном FPM это всплывает редко, а под Octane превращается в чужие данные в ответе.

Лечится одним из трёх способов, по возрастанию сложности:

// 1. Не хранить запрос вообще: получать его в момент вызова
public function handle(): void
{
    $ip = request()->ip();
}

// 2. Принимать запрос параметром метода, а не конструктора
public function handle(Request $request): void
{
    $ip = $request->ip();
}

Третий способ нужен, когда объект обязан хранить запрос у себя — например, это адаптер к стороннему SDK. Тогда попросите контейнер обновлять ссылку при каждой пересборке request:

$this->app->singleton(TrackingClient::class, function ($app) {
    $client = new TrackingClient($app['request']);

    // при каждой пересборке 'request' объекту подсунут актуальный запрос
    $app->refresh('request', $client, 'setRequest');

    return $client;
});

refresh() — это обёртка над rebinding(): как только в контейнере переопределяется request, у объекта вызовется setRequest() с новым экземпляром. Ровно так внутри устроены сами компоненты Laravel, которые вынуждены держать запрос.

То же рассуждение касается всего, что живёт ровно один запрос: аутентифицированного пользователя, текущей локали, идентификатора трассировки.

Контейнер как справочная служба. Когда app(SomeService::class) разбросан по всему коду, вы формально используете контейнер, но реально вернулись к жёсткой связанности: класс снова сам добывает зависимости, просто через посредника. Зависимости при этом не видны в сигнатуре, а тестировать становится тяжело. Правило: объявляйте зависимости в конструкторе, к контейнеру обращайтесь напрямую только там, куда внедрение не дотягивается (фабрики, ленивое создание тяжёлых объектов, устаревший код).

Интерфейс ради интерфейса. Если у абстракции всегда будет ровно одна реализация и подменять её вы не собираетесь даже в тестах, интерфейс добавляет файл и не добавляет пользы. Абстракции стоят денег, они должны окупаться.

Циклическая зависимость. A требует B, B требует A — контейнер уйдёт в бесконечную рекурсию. Отдельной проверки на цикл в нём нет, поэтому осмысленного исключения вы не увидите: процесс упрётся в лимит памяти, в максимальную вложенность вызовов (если стоит Xdebug) или просто рухнет. Полезный приём при отладке — посмотреть на стек вызовов: повторяющийся фрагмент из Container::build() сразу покажет пару виновников. Это не баг контейнера, а сигнал, что ответственность между классами распределена неудачно.

15. Пишем свой контейнер

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

<?php

use Closure;
use ReflectionClass;
use RuntimeException;

class MiniContainer
{
    /** Рецепты создания: 'Интерфейс' => ['concrete' => ..., 'shared' => bool] */
    protected array $bindings = [];

    /** Уже созданные общие экземпляры */
    protected array $instances = [];

    /** Что сейчас собираем — нужно, чтобы поймать циклическую зависимость */
    protected array $buildStack = [];

    public function bind(string $abstract, Closure|string|null $concrete = null, bool $shared = false): void
    {
        $this->bindings[$abstract] = [
            'concrete' => $concrete ?? $abstract,
            'shared'   => $shared,
        ];
    }

    public function singleton(string $abstract, Closure|string|null $concrete = null): void
    {
        $this->bind($abstract, $concrete, true);
    }

    public function instance(string $abstract, object $object): void
    {
        $this->instances[$abstract] = $object;
    }

    /** Главный метод: получить объект по имени */
    public function make(string $abstract): mixed
    {
        // 1. Уже создавали и договаривались хранить? Отдаём то же самое.
        if (isset($this->instances[$abstract])) {
            return $this->instances[$abstract];
        }

        // 2. Защита от циклов: A требует B, B требует A.
        if (isset($this->buildStack[$abstract])) {
            throw new RuntimeException(
                'Циклическая зависимость: ' . implode(' -> ', array_keys($this->buildStack)) . " -> {$abstract}."
            );
        }

        $this->buildStack[$abstract] = true;

        try {
            $binding  = $this->bindings[$abstract] ?? null;
            $concrete = $binding['concrete'] ?? $abstract;

            if ($concrete instanceof Closure) {
                // 3. Рецепт-функция: просто выполняем её.
                $object = $concrete($this);
            } elseif ($concrete === $abstract) {
                // 4. Рецепта нет (или он указывает сам на себя) — строим класс.
                $object = $this->build($concrete);
            } else {
                // 5. Рецепт — другое имя. Разрешаем его целиком,
                //    чтобы сработали привязки, зарегистрированные уже для него.
                $object = $this->make($concrete);
            }
        } finally {
            unset($this->buildStack[$abstract]);
        }

        // 6. Синглтон? Запоминаем.
        if ($binding !== null && $binding['shared']) {
            $this->instances[$abstract] = $object;
        }

        return $object;
    }

    /** Сборка класса через рефлексию — то самое автоматическое связывание */
    protected function build(string $class): object
    {
        if (! class_exists($class)) {
            throw new RuntimeException("Не найден класс {$class}.");
        }

        $reflector = new ReflectionClass($class);

        if (! $reflector->isInstantiable()) {
            throw new RuntimeException(
                "Нельзя создать {$class}: это интерфейс или абстрактный класс. Нужна привязка."
            );
        }

        $constructor = $reflector->getConstructor();

        // Конструктора нет — создаём напрямую
        if ($constructor === null) {
            return new $class();
        }

        $arguments = [];

        foreach ($constructor->getParameters() as $parameter) {
            $type = $parameter->getType();

            // Скаляр, отсутствие типа, объединение или пересечение типов —
            // всё это наш учебный контейнер разрешить не умеет.
            // Единственное, что мы можем сделать, — взять значение по умолчанию.
            if ($type === null || ! $type instanceof \ReflectionNamedType || $type->isBuiltin()) {
                if ($parameter->isDefaultValueAvailable()) {
                    $arguments[] = $parameter->getDefaultValue();
                    continue;
                }

                throw new RuntimeException(
                    "Не могу разрешить параметр \${$parameter->getName()} класса {$class}."
                );
            }

            // Тип — класс или интерфейс: рекурсивно создаём его.
            // Если не вышло, но параметр допускает значение по умолчанию, берём его.
            try {
                $arguments[] = $this->make($type->getName());
            } catch (RuntimeException $e) {
                if (! $parameter->isDefaultValueAvailable()) {
                    throw $e;
                }

                $arguments[] = $parameter->getDefaultValue();
            }
        }

        return $reflector->newInstanceArgs($arguments);
    }
}

Проверим:

interface NotificationSender {
    public function send(string $phone, string $text): void;
}

class SmsSender implements NotificationSender {
    public function __construct(private string $apiKey) {}
    public function send(string $phone, string $text): void {
        echo "SMS на {$phone}: {$text}\n";
    }
}

class OrderService {
    public function __construct(public NotificationSender $sender) {}
}

$container = new MiniContainer();

$container->bind(NotificationSender::class, function () {
    return new SmsSender('секретный-ключ');
});

$service = $container->make(OrderService::class);
$service->sender->send('+7999', 'Заказ подтверждён');

Мы нигде не сказали, как создавать OrderService. Контейнер сам прочитал конструктор, увидел NotificationSender, нашёл для него рецепт, выполнил его и собрал всё вместе.

В Laravel происходит похожий процесс: контейнер анализирует зависимости, находит зарегистрированные правила и создаёт объекты. Но реальный контейнер значительно сложнее: он поддерживает контекстные привязки и атрибуты, метки, события разрешения, extend, scoped, rebinding, разные времена жизни объектов, передачу параметров и множество других случаев.

Чего наш мини-контейнер намеренно не умеет — полезно держать в голове, если вдруг захочется взять его как основу:

  • variadic-параметры (__construct(Handler ...$handlers)) — Laravel умеет собирать их из привязки-массива или из метки;
  • типы self, static, parent — формально это ReflectionNamedType с isBuiltin() === false, и make('self') предсказуемо упадёт;
  • makeWith, то есть передачу части аргументов вручную;
  • scoped и сброс таких экземпляров между запросами;
  • extend, метки, коллбэки resolving и контекстные привязки.

Зато основная идея — прочитать конструктор рефлексией и рекурсивно собрать зависимости — здесь ровно та же, что и в настоящем контейнере.

16. Итог

Если оставить одну мысль, пусть будет эта:

Классы не должны сами добывать то, чем пользуются, — они должны честно объявлять это в конструкторе. Это внедрение зависимостей. А контейнер — то, что делает такой стиль посильным: он берёт на себя сборку, которая иначе расползлась бы по всему приложению.

Всё остальное — следствия:

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

Практический совет напоследок.

Не регистрируйте вручную каждый класс и не создавайте интерфейсы просто «на всякий случай». Автоматическое разрешение зависимостей покрывает множество обычных случаев без какой-либо настройки. Явные привязки особенно часто нужны, когда используется интерфейс, который нельзя создать напрямую, когда в конструктор нужно передать конкретные значения, или когда требуется особое управление созданием и временем жизни объекта.

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

Сообщение Разбираемся с сервис-контейнером в Laravel. появились сначала на mcodex.

]]> Воркеры в Laravel https://mcodex.ru/workers-in-laravel/ Sat, 08 Aug 2026 09:32:03 +0000 https://mcodex.ru/?p=389 «Воркер» — это не какая-то особая сущность фреймворка. Это обычный долгоживущий PHP-процесс, запущенный из командной строки, который крутит бесконечный цикл и не завершается. Когда вы выполняете php artisan queue:work, PHP-скрипт запускается и просто не возвращает управление. Внутри у него: Всё. Воркер — это исполнитель цикла «взять → выполнить → повторить». Чем воркер принципиально отличается от ... Читать далее

Сообщение Воркеры в Laravel появились сначала на mcodex.

]]> «Воркер» — это не какая-то особая сущность фреймворка. Это обычный долгоживущий PHP-процесс, запущенный из командной строки, который крутит бесконечный цикл и не завершается.

Когда вы выполняете php artisan queue:work, PHP-скрипт запускается и просто не возвращает управление. Внутри у него:

while (true) {
    $job = взять задачу из Redis;

    if (!$job) {
        sleep(3);          // очередь пуста
        continue;
    }

    unserialize($job);     // развернуть объект
    $job->handle();        // выполнить

    удалить задачу из Redis (или вернуть при ошибке);

    проверить: не пора ли мне умереть?  // память, --max-jobs, --max-time, сигнал
}

Всё. Воркер — это исполнитель цикла «взять → выполнить → повторить».

Чем воркер принципиально отличается от обычного PHP-запроса

Вот это главное, что нужно уложить в голове.

При работе через PHP-FPM каждый HTTP-запрос — это чистый лист: фреймворк загружается, отрабатывает, умирает, вся память освобождается. Утечки не страшны, «протухшее» состояние невозможно.

Воркер устроен наоборот: фреймворк бутстрапится один раз, при старте процесса, и дальше сотни задач выполняются в одном и том же экземпляре приложения. Отсюда три практических следствия:

Утечки памяти накапливаются. Процесс, отработавший сутки, может съесть гигабайт. Поэтому у воркера есть --memory=128: после каждой задачи он проверяет memory_get_usage() и, превысив лимит, сам завершается — чтобы менеджер процессов поднял свежий.

Изменения в коде не подхватываются. Воркер держит в памяти классы, загруженные при старте. Задеплоили новую версию job — процесс продолжит выполнять старую. Именно поэтому после каждого деплоя обязателен php artisan queue:restart (или horizon:terminate).

Состояние приложения «протухает». Синглтоны в контейнере, статические свойства, уже разрешённые сервисы, Auth::user() от предыдущей задачи, изменённая конфигурация — всё это переживает границу между задачами. Классический баг: в одной job поменяли локаль или подключение к БД, и следующие сто задач работают с чужими настройками. Laravel сбрасывает часть состояния между задачами, но не всё — на свои синглтоны полагаться нельзя.

Есть альтернатива — php artisan queue:listen: он поднимает отдельный дочерний процесс на каждую задачу, то есть чистый лист как при HTTP. Ни утечек, ни протухшего кода, ни queue:restart. Расплата — бутстрап фреймворка на каждую задачу, что в разы медленнее. В продакшене используют queue:work, listen — иногда в разработке.

Параллелизм — это просто много процессов

В PHP нет потоков. «Десять воркеров» означает буквально десять независимых процессов ОС, у каждого свой PID и своя память. Они ничего друг о друге не знают и координируются исключительно через Redis.

Отсюда вопрос: почему два воркера не схватят одну задачу? Потому что операция «забрать» атомарна — Laravel выполняет Lua-скрипт, который одним неделимым действием вынимает задачу из списка и кладёт её в sorted set queues:default:reserved с меткой времени. Второй воркер её там уже не увидит. Если первый умрёт, не доделав, — через retry_after секунд задача из reserved вернётся в основной список и достанется кому-то другому.

Как воркер умирает

Штатных причин несколько, и все они — часть дизайна:

  • --timeout — задача выполняется дольше лимита. Реализовано через pcntl_alarm(): перед запуском job взводится будильник, по срабатыванию процесс убивается. Это единственный способ прервать зависший handle() — потому и нужно расширение pcntl.
  • --memory — превышен лимит памяти, воркер выходит после текущей задачи.
  • --max-jobs / --max-time — профилактический перезапуск: отработал 1000 задач или час, вышел, поднялся заново с чистой памятью.
  • Сигнал — SIGTERM при деплое или остановке. Воркер дорабатывает текущую задачу и выходит.

Во всех случаях подразумевается, что процесс кто-то перезапустит. Сам по себе воркер не самовосстанавливается — «умереть и переродиться» и есть его штатный способ обновиться. Именно это делает Horizon (для своих воркеров) или supervisord (для Horizon в целом).

Где воркеры в схеме Очереди в Laravel, Horizon, Supervisor

В тексте статьи воркеры — нижний уровень иерархии, процессы php artisan horizon:work. Это те же самые queue:work по сути, только запущенные не вами вручную, а процессом horizon:supervisor согласно config/horizon.php, и с дополнительной отправкой метрик в Redis для дашборда.

Сообщение Воркеры в Laravel появились сначала на mcodex.

]]> Очереди в Laravel, Horizon, Supervisor https://mcodex.ru/laravel-horizon-supervisor/ Sat, 08 Aug 2026 09:07:50 +0000 https://mcodex.ru/?p=381 Как работают очереди в Laravel: Redis + Horizon + Supervisor Разберём эту систему по слоям: от концепции очередей до того, как Linux следит, чтобы всё это не падало. 1. Зачем вообще нужны очереди Когда пользователь делает запрос (например, регистрируется на сайте), некоторые действия долгие: отправить email, сгенерировать PDF, обработать видео, дёрнуть внешний API. Если делать ... Читать далее

Сообщение Очереди в Laravel, Horizon, Supervisor появились сначала на mcodex.

]]> Как работают очереди в Laravel: Redis + Horizon + Supervisor

Разберём эту систему по слоям: от концепции очередей до того, как Linux следит, чтобы всё это не падало.

1. Зачем вообще нужны очереди

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

Решение: вместо того чтобы выполнять тяжёлую работу прямо в HTTP-запросе, Laravel кладёт задачу («job») в очередь и сразу отвечает пользователю. Кто-то другой (worker) потом эту задачу заберёт и выполнит в фоне.

ProcessPodcast::dispatch($podcast); // мгновенно, не блокирует ответ

2. Redis как хранилище очереди

Очереди нужно где-то хранить. Laravel поддерживает разные драйверы (database, sqs, redis и т.д.). Redis — самый популярный выбор для очередей, потому что:

  • он in-memory и очень быстрый;
  • имеет встроенные структуры данных, удобные для очередей (списки, sorted sets);
  • поддерживает атомарные операции. Важно, чтобы два worker’а не схватили одну и ту же задачу. Laravel реализует эту атомарность через Lua-скрипты, выполняемые Redis целиком, без возможности вклиниться между шагами.

Технически, когда вы вызываете dispatch(), Laravel сериализует job (класс, его свойства) и помещает её в Redis-очередь (список queues:default).

Подробнее про сериализацию задачи.

Сериализуется не класс, а объект класса Job.

Что реально уходит в Redis

В Redis-список кладётся JSON-строка — конверт с метаданными. А сам объект job лежит внутри неё отдельным полем, сериализованный нативным PHP serialize():

// Illuminate\Queue\Queue::createObjectPayload()
'data' => [
    'commandName' => get_class($job),        // 'App\Jobs\ProcessPodcast'
    'command'     => serialize(clone $job),  // ← вот здесь сам инстанс
],

Итоговый payload примерно такой:

{
  "uuid": "9a1c...",
  "displayName": "App\\Jobs\\ProcessPodcast",
  "job": "Illuminate\\Queue\\CallQueuedHandler@call",
  "maxTries": 3,
  "timeout": 60,
  "retryUntil": null,
  "attempts": 0,
  "data": {
    "commandName": "App\\Jobs\\ProcessPodcast",
    "command": "O:24:\"App\\Jobs\\ProcessPodcast\":1:{s:7:\"podcast\";..."
  }
}

Метаданные (maxTries, timeout, retryUntil, attempts) вынесены наружу специально: воркеру нужно прочитать их до того, как он развернёт объект, например, чтобы решить, не пора ли отправить задачу в failed_jobs. На стороне воркера CallQueuedHandler@call делает unserialize($data['command']) и вызывает handle() через контейнер (поэтому в handle() работает method injection).

clone перед serialize() нужен, чтобы магия __serialize()/__sleep() не покалечила исходный объект в текущем процессе — он ведь может использоваться дальше.

Практические следствия

Сериализуются все свойства: public, protected, private.
Значит, в job нельзя класть то, что PHP сериализовать не умеет:
PDO-соединения, файловые дескрипторы, ресурсы, замыкания.
Для очередей из замыканий (dispatch(function () { ... })) Laravel подключает отдельный пакет laravel/serializable-closure.

Трейт SerializesModels меняет правила для Eloquent. Он перехватывает __serialize() и подменяет модель на ModelIdentifier — класс, id, имя соединения и список загруженных связей.
При десериализации модель заново достаётся из БД.
Два следствия:

  • воркер видит актуальное состояние записи, а не снимок на момент dispatch — обычно это то, что нужно;
  • если запись успели удалить, unserialize бросит ModelNotFoundException. По умолчанию (deleteWhenMissingModels) такая задача тихо удаляется, не попадая в failed_jobs.

Для отложенных задач (->delay()) и для задач, уже взятых воркером в работу («reserved»), Laravel использует sorted set: задачи там отсортированы по timestamp’у, когда они должны стать доступными снова.

Как воркер узнаёт о новой задаче

Здесь важная деталь, которую часто описывают неверно. По умолчанию воркер не висит в блокирующем ожидании, он работает в режиме polling:

  1. пытается забрать задачу из очереди;
  2. если очередь пуста — спит --sleep=3 секунды;
  3. повторяет.

Блокирующее ожидание (BLPOP по служебному ключу queues:default:notify) включается, только если в config/queue.php для redis-подключения явно задан block_for:

'redis' => [
    'driver' => 'redis',
    'connection' => 'default',
    'queue' => env('REDIS_QUEUE', 'default'),
    'retry_after' => 90,
    'block_for' => 5, // по умолчанию null → polling
],

Блокирующий режим снижает задержку подхвата задачи и нагрузку на Redis, но занимает соединение на всё время ожидания.

retry_after и timeout — источники дублей

Два параметра, которые обязательно надо согласовать:

  • retry_after (в config/queue.php). Через сколько секунд Laravel считает задачу «зависшей» и возвращает её в очередь;
  • timeout воркера (в Horizon — ключ timeout в config/horizon.php). Через сколько секунд принудительно убить процесс, выполняющий job.

retry_after должен быть строго больше самого долгого timeout. Иначе задача будет отдана второму воркеру, пока первый её ещё выполняет и вы получите дублирующиеся отправки писем и списания.

3. Кто выполняет задачи: воркеры

См: Что такое Воркеры

Сама по себе задача в Redis просто лежит и ждёт. Её должен кто-то забрать и выполнить. Это делает команда:

php artisan queue:work redis

Это долгоживущий процесс: обычно он запускается один раз и работает непрерывно (в цикле: взять задачу → выполнить → взять следующую). При этом worker может завершиться по различным причинам, например, из-за заданных ограничений времени/количества jobs (--max-time, --max-jobs), превышения лимита памяти (--memory), ошибки или получения сигнала. Именно поэтому его обычно запускают под управлением отдельного менеджера процессов или Horizon.

Проблема: что если worker упадёт (ошибка, сервер перезагрузился, память закончилась)? Кто его перезапустит? Тут в игру вступают Horizon и Supervisor.

Задачи, исчерпавшие попытки, попадают в failed jobs, по умолчанию в таблицу failed_jobs (драйвер database). Horizon дополнительно хранит их копию в Redis, чтобы показывать в дашборде и давать кнопку retry; срок хранения этих данных задаётся в config/horizon.php (trim / failed в секции хранения).

4. Что такое Laravel Horizon

Horizon — это надстройка над обычными Redis-воркерами, которая даёт:

  1. Красивый дашборд. Видно, сколько задач выполнено, сколько упало, сколько задач в очереди, throughput в реальном времени, время выполнения job’ов.
  2. Управление несколькими очередями и воркерами из одного конфига (config/horizon.php). Можно описать, сколько процессов держать на очереди high, сколько на default, с авто-масштабированием ('balance' => 'auto').
  3. Единую точку запуска. Вместо того чтобы вручную поднимать десяток queue:work процессов, вы запускаете один процесс:
php artisan horizon

Horizon сам, внутри себя, запускает и следит за нужным числом дочерних worker-процессов согласно конфигу (supervisors в терминологии Horizon — не путать с Linux Supervisor, это разные вещи с одинаковым названием!).

Два важных нюанса:

  • Horizon работает только с Redis-драйвером очередей. Это не универсальный менеджер для любых очередей.
  • Нужны PHP-расширения pcntl и posix. Без них не работает обработка сигналов, а значит — ни horizon:terminate, ни корректный graceful shutdown, ни контроль дочерних процессов.

5. Два разных «Supervisor», не запутайтесь.

Тут стоит остановиться отдельно, потому что термин «supervisor» используется на двух уровнях:

  • Horizon Supervisor. Это логическая сущность внутри config/horizon.php, группа воркеров, обслуживающих определённые очереди (например, supervisor-1 держит 10 процессов на очереди emails).
  • Linux Supervisor (supervisord). Это отдельная системная программа, вообще не знающая ничего про Laravel, чья задача — следить, чтобы один конкретный процесс (в нашем случае php artisan horizon) был постоянно запущен.

Важно: Horizon не порождает воркеров напрямую из мастер-процесса. Иерархия трёхуровневая — на каждую supervisor-группу из конфига поднимается свой процесс-посредник:

supervisord (Linux)
   └── следит за процессом: php artisan horizon        ← MasterSupervisor
              └── php artisan horizon:supervisor ...   ← по процессу на каждую
                    │                                     supervisor-группу из конфига
                    └── php artisan horizon:work ...    ← собственно воркеры
                              └── каждый воркер читает задачи из Redis

Именно поэтому в ps aux | grep horizon процессов больше, чем сумма maxProcesses по конфигу: к воркерам добавляются мастер и по одному процессу на группу.

6. Зачем нужен Linux Supervisor, если есть Horizon

Сам php artisan horizon — это тоже просто процесс. Если сервер перезагрузится, если процесс упадёт по ошибке PHP, если кто-то случайно его убьёт — задачи просто перестанут обрабатываться, и никто не заметит, пока очередь не разрастётся до небес.

Supervisord решает эту проблему на уровне ОС: он запускает процесс, следит за его PID, и если процесс завершается — перезапускает автоматически. Конфиг обычно выглядит так:

[program:horizon]
process_name=%(program_name)s
command=/usr/bin/php8.3 /var/www/project/artisan horizon
autostart=true
autorestart=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/project/storage/logs/horizon.log
stopwaitsecs=3600

Разберём ключевые директивы:

  • command — указывайте абсолютный путь к бинарнику PHP: у supervisord свой PATH, и просто php может не разрешиться (или разрешиться не в ту версию).
  • autostart — запускать при старте supervisord (обычно при загрузке сервера).
  • autorestart — если процесс завершился, запустить заново.
  • numprocs=1 — явно фиксируем: Horizon должен быть в единственном экземпляре. Два параллельных мастер-процесса — это двойной набор воркеров и гонки.
  • user — от чьего имени работает процесс (обычно тот же, что и у веб-сервера, ради прав доступа к файлам).
  • stopwaitsecs=3600 — сколько supervisord ждёт после отправки SIGTERM, прежде чем добить процесс через SIGKILL. Это применяется при supervisorctl stop horizon, supervisorctl restart horizon и при выключении/перезагрузке сервера. Значение должно быть не меньше максимально возможного времени выполнения job — иначе supervisord прибьёт Horizon посреди работы и задача оборвётся.

Обратите внимание: stopwaitsecs не участвует в сценарии php artisan horizon:terminate — там Horizon завершается сам, и supervisord просто фиксирует выход процесса. Подробнее — в следующем разделе.

7. Как это выглядит при деплое

Правильный паттерн деплоя с Horizon+Supervisor такой:

php artisan horizon:terminate

Это не отключает конфигурацию Supervisor. Команда через Redis отправляет сигнал текущему процессу Horizon: тот инициирует graceful shutdown — текущие jobs получают возможность завершиться, новые не берутся, после чего воркеры и сам мастер-процесс выходят.

Supervisord, увидев, что процесс завершился (а autorestart=true), запускает новый процесс php artisan horizon — уже с новым кодом. Так выполняется graceful restart Horizon после деплоя.

Здесь supervisord ничего не ждёт и stopwaitsecs не применяется: он реагирует на уже случившийся выход процесса, а не сам его останавливает.

8. Собираем всю картину воедино

  1. Ваш Laravel-код вызывает Job::dispatch() → задача сериализуется и пушится в Redis-список (или в sorted set, если задан delay).
  2. php artisan horizon — единственный процесс, за которым следит Linux Supervisor (autorestart, живёт вечно).
  3. Внутри себя Horizon поднимает по процессу horizon:supervisor на каждую supervisor-группу из config/horizon.php, а те, в свою очередь, — N процессов-воркеров (сколько на какую очередь, авто-баланс).
  4. Каждый воркер опрашивает Redis (или блокирующе ждёт, если задан block_for), забирает задачу и выполняет. Horizon управляет worker-процессами и собирает метрики; данные Horizon тоже хранятся в Redis.
  5. Если отдельный worker завершается, его дальнейшей судьбой управляет сам Horizon. Если завершается процесс Horizon, Linux Supervisor запускает его заново.
  6. Дашборд Horizon (/horizon в браузере) использует данные Horizon из Redis и показывает состояние очередей и worker-процессов.

Что стоит посмотреть своими руками

Чтобы это закрепилось не только в теории, полезно:

  • Открыть config/horizon.php и посмотреть на секцию environments — там видно, как задаются supervisor-группы (supervisor-1) и сколько процессов на какую очередь.
  • Выполнить ps aux | grep horizon и увидеть все три уровня: мастер, horizon:supervisor, horizon:work.
  • Зайти в Redis через redis-cli и посмотреть, сколько задач реально лежит в очереди. Учтите, что Laravel добавляет к ключам префикс из config/database.php (обычно laravel_database_), поэтому голый LLEN queues:default вернёт 0. Сначала найдите реальный ключ: redis-cli --scan --pattern '*queues*' redis-cli LLEN laravel_database_queues:default Это хорошо снимает «магию» с процесса.
  • Посмотреть supervisorctl status на сервере — увидеть, что Horizon значится там просто как один managed-процесс.
  • Намеренно уронить Horizon и посмотреть, как быстро supervisord его поднимет обратно. Используйте kill <pid> (SIGTERM) или supervisorctl stop horizon, а не kill -9: SIGKILL нельзя перехватить, мастер умрёт мгновенно, а дочерние horizon:supervisor и horizon:work останутся висеть сиротами. Horizon умеет подчищать осиротевшие группы, но не мгновенно — какое-то время на сервере будет двойной набор процессов.

Сообщение Очереди в Laravel, Horizon, Supervisor появились сначала на mcodex.

]]> Полезные команды Artisan https://mcodex.ru/artisan-commands/ Wed, 01 Jul 2026 15:24:06 +0000 https://mcodex.ru/?p=313 Проверка соответсвия времени и таймзон на сервере и в базе данных

Сообщение Полезные команды Artisan появились сначала на mcodex.

]]> Проверка соответсвия времени и таймзон на сервере и в базе данных

php artisan tinker --execute="echo json_encode(DB::select('SELECT NOW() as now, UTC_TIMESTAMP() as utc, @@global.time_zone as g, @@session.time_zone as s')[0]);"

Сообщение Полезные команды Artisan появились сначала на mcodex.

]]>