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,
    ) {}
}

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);

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

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

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

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

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

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

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

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

$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, 'Заказ подтверждён');
    }
}

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,
    ) {}
}

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, 'Заказ подтверждён');
    }
}

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,
    ) {}
}

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'),
    )
);

$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,
    ) {}
}

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].

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

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'),
        );
    });
}

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(...) для остальных зависимостей
});

$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);

$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);
});

$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));
});

$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);

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

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

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

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

$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(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'));

$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([VideoController::class, UploadController::class])
    ->needs(Filesystem::class)
    ->give(fn () => Storage::disk('s3'));

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

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

$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\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,
    ) {}
}

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');

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();
    }
}

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']);

// Предпочтительный способ: просто объявите тип, 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 — из параметров маршрута
}

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

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

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

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

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'));
    }
}

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

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];
    }
}
```

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';
    }
}

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();
}

$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));
});

$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(...);

$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);

$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');

$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();
}

// 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;
});

$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);
    }
}

<?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', 'Заказ подтверждён');

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.

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

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

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

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

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

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

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.

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

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

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

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

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

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),  // ← вот здесь сам инстанс
],

// 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\";..."
  }
}

{
  "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' => [
    '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

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

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

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

[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

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.

1. Устанаваливаем утилиту mkcert

sudo apt update
sudo apt install libnss3-tools
sudo apt install mkcert
sudo apt install golang-go
go install filippo.io/mkcert@latest

sudo apt update
sudo apt install libnss3-tools
sudo apt install mkcert
sudo apt install golang-go
go install filippo.io/mkcert@latest

2. Создаем корневой сертификат

mkcert -install

mkcert -install

3. Создаем сертификат для локального сайта

mkdir -p ~/certs && cd ~/certs
mkcert my-project.local localhost 127.0.0.1

mkdir -p ~/certs && cd ~/certs
mkcert my-project.local localhost 127.0.0.1

4. Проверяем папку, должны появится файлы

~/certs ls 
# my-project.local+2.pem (сертификат) 
# my-project.local+2-key.pem (ключ)

~/certs ls 
# my-project.local+2.pem (сертификат) 
# my-project.local+2-key.pem (ключ)

5. Добавляем сертфикат в настройку Nginx

server {
    listen 443 ssl;
    server_name my-project.local;

    ssl_certificate     /home/username/certs/my-project.local+2.pem;
    ssl_certificate_key /home/username/certs/my-project.local+2-key.pem;

    root /var/www/my-project;
    index index.html;
    .....
}

server {
    listen 80;
    server_name my-project.local;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name my-project.local;

    ssl_certificate     /home/username/certs/my-project.local+2.pem;
    ssl_certificate_key /home/username/certs/my-project.local+2-key.pem;

    root /var/www/my-project;
    index index.html;
    .....
}

server {
    listen 80;
    server_name my-project.local;
    return 301 https://$host$request_uri;
}

6. Перегружаем Nginx

sudo nginx -t
sudo systemctl reload nginx

sudo nginx -t
sudo systemctl reload nginx

Сообщение Локальный сайт с SSL появились сначала на mcodex.

# поиск в определенном файле
grep "строка которую ищем" file.txt

# поиск во всех файлах и папках в определенной папке
grep -r "строка которую ищем" /etc/log

# поиск во всех файлах и папках в текущей папке
grep -r "строка которую ищем" .

# показываем строки (-n) и игнорируем регистр (-i)
grep -rni "строка которую ищем" .

# ищем во всех файлах и папках, кроме исключений
grep -rn \
  --exclude-dir=vendor \
  --exclude-dir=.git \
  "строка которую ищем" .  

# поиск в определенном файле
grep "строка которую ищем" file.txt

# поиск во всех файлах и папках в определенной папке
grep -r "строка которую ищем" /etc/log

# поиск во всех файлах и папках в текущей папке
grep -r "строка которую ищем" .

# показываем строки (-n) и игнорируем регистр (-i)
grep -rni "строка которую ищем" .

# ищем во всех файлах и папках, кроме исключений
grep -rn \
  --exclude-dir=vendor \
  --exclude-dir=.git \
  "строка которую ищем" .  

Сообщение Полезные консольные команды в Ubuntu появились сначала на 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]);"

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.

• Не отслеживать изменение прав на файлы и папки
• Исправить описание в последнем коммите
• Анализ проекта
• Изменить удаленный репозиторий
• Тэги
• История изменений
• Переименование ветки

Не отслеживать изменение прав

git config core.fileMode false

git config core.fileMode false

Исправить описание в последнем коммите

git commit --amend -m "New commit message"

git commit --amend -m "New commit message"

Анализ проекта

# Какие файлы меняются чаще всего
git log --format=format: --name-only --since="1 year ago" | sort | uniq -c | sort -nr | head -20

# Все контрибьюторы отсортированные по числу коммитов
git shortlog -sn --no-merges

# Кто активен за последние полгода
git shortlog -sn --no-merges --since="6 months ago"

# Количество коммитов помесячно
git log --format='%ad' --date=format:'%Y-%m' | sort | uniq -c

#Где скапливаются баги, отфильтровано по коммитам с ключевыми словами
git log -i -E --grep="fix|bug|broken" --name-only --format='' | sort | uniq -c | sort -nr | head -20

# Как часто делаются revert/hotfix
git log --oneline --since="1 year ago" | grep -iE 'revert|hotfix|emergency|rollback'

# Какие файлы меняются чаще всего
git log --format=format: --name-only --since="1 year ago" | sort | uniq -c | sort -nr | head -20

# Все контрибьюторы отсортированные по числу коммитов
git shortlog -sn --no-merges

# Кто активен за последние полгода
git shortlog -sn --no-merges --since="6 months ago"

# Количество коммитов помесячно
git log --format='%ad' --date=format:'%Y-%m' | sort | uniq -c

#Где скапливаются баги, отфильтровано по коммитам с ключевыми словами
git log -i -E --grep="fix|bug|broken" --name-only --format='' | sort | uniq -c | sort -nr | head -20

# Как часто делаются revert/hotfix
git log --oneline --since="1 year ago" | grep -iE 'revert|hotfix|emergency|rollback'

Изменить удаленный репозиторий
Проект склонирован через https, нужно изменить на ssh

# текущее состояние
git remote -v
#origin https://gitlab.com/my-username/my-project.git (fetch)
#origin https://gitlab.com/my-username/my-project.git (push)


# замена
git remote set-url origin git@gitlab.com:my-username/my-project.git

# проверка
git remote -v
# origin git@gitlab.com:my-username/my-project.git (fetch)
# origin git@gitlab.com:my-username/my-project.git (push)

# текущее состояние
git remote -v
#origin https://gitlab.com/my-username/my-project.git (fetch)
#origin https://gitlab.com/my-username/my-project.git (push)


# замена
git remote set-url origin git@gitlab.com:my-username/my-project.git

# проверка
git remote -v
# origin git@gitlab.com:my-username/my-project.git (fetch)
# origin git@gitlab.com:my-username/my-project.git (push)

Тэги

# просмотреть список тэгов
git tag

# посмотреть информацию по конкретному тэгу
git show 1.2.4

# добавить тэг
git tag -a v1.0 -m "version 1.0"

# тэги по умолчанию не пушатся в удаленный репозиторий. 
# запушить конкретный тэг 
git push origin v1.1

# запушить все тэги 
git push origin --tags

# запушить коммит с новым тэгом 
git push --follow-tags

# можно тэгом помечать ранее сделанный коммит.
# смотрим лог коммитов с хэшами: 
git log --pretty=oneline

# берем первые 7 символов хэша нужного коммита и ставим тэг
git tag -a v1.0 -m "release v1.0" 700b806

# просмотреть список тэгов
git tag

# посмотреть информацию по конкретному тэгу
git show 1.2.4

# добавить тэг
git tag -a v1.0 -m "version 1.0"

# тэги по умолчанию не пушатся в удаленный репозиторий. 
# запушить конкретный тэг 
git push origin v1.1

# запушить все тэги 
git push origin --tags

# запушить коммит с новым тэгом 
git push --follow-tags

# можно тэгом помечать ранее сделанный коммит.
# смотрим лог коммитов с хэшами: 
git log --pretty=oneline

# берем первые 7 символов хэша нужного коммита и ставим тэг
git tag -a v1.0 -m "release v1.0" 700b806

История изменений

# история коммитов в виде дерева
git log --pretty=oneline --graph

# вывод информации по изменениям, которые внесли коммиты (список файлов)
git log --stat

# изменения в последних 2-х коммитах
git log -p -2 

# не показывать коммиты слияния
git log --no-merges 

# +фильтр по автору
git log --stat --no-merges --author=johndoe

git log -- path/to/file

# изменения в конкретном файле
# красный - что было
# зеленый - что стало 
git log -p --no-merges --author=johndoe -- resources/views/en/page.blade.php

# изменения в последнем коммите
git log -p -1 -- resources/views/en/page.blade.php

# или
git diff branch1 branch2 

# какие есть коммиты в ветке develop, которых нет в main
# можно выполнять как в develop, так и в main
git log develop --not main 

# какие изменения будут внесены из develop в main
git log develop -p main

# кто и когда делал изменения каждой строки файла
git blame resources/views/home.blade.php

# история коммитов в виде дерева
git log --pretty=oneline --graph

# вывод информации по изменениям, которые внесли коммиты (список файлов)
git log --stat

# изменения в последних 2-х коммитах
git log -p -2 

# не показывать коммиты слияния
git log --no-merges 

# +фильтр по автору
git log --stat --no-merges --author=johndoe

git log -- path/to/file

# изменения в конкретном файле
# красный - что было
# зеленый - что стало 
git log -p --no-merges --author=johndoe -- resources/views/en/page.blade.php

# изменения в последнем коммите
git log -p -1 -- resources/views/en/page.blade.php

# или
git diff branch1 branch2 

# какие есть коммиты в ветке develop, которых нет в main
# можно выполнять как в develop, так и в main
git log develop --not main 

# какие изменения будут внесены из develop в main
git log develop -p main

# кто и когда делал изменения каждой строки файла
git blame resources/views/home.blade.php

Переименование ветки

В локальном репозитории есть ветка, в ней коммиты, ветка запушена в origin. Необходимо переименовать и локальную и удаленную ветки.

# переименовываем локальную ветку
git branch -m новое-имя

# пушим переименованную ветку
git push origin -u новое-имя

# удаляем старую ветку из origin
git push origin --delete старое-имя

# переименовываем локальную ветку
git branch -m новое-имя

# пушим переименованную ветку
git push origin -u новое-имя

# удаляем старую ветку из origin
git push origin --delete старое-имя

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

curl -fsSL https://get.docker.com | sh

# добавляем текущего пользователя в группу docker
sudo usermod -aG docker $USER
newgrp docker

curl -fsSL https://get.docker.com | sh

# добавляем текущего пользователя в группу docker
sudo usermod -aG docker $USER
newgrp docker

2. Файл docker-compose.yaml

Создаем папку, например, /docker-containers/mysql, в ней файл docker-compose.yaml

services:
  mysql:
    image: mysql:8.0
    container_name: mysql_container
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: your_root_password
      MYSQL_DATABASE: my_project_db
      MYSQL_USER: my_project_user
      MYSQL_PASSWORD: my_project_password
    volumes:
      - mysql_data:/var/lib/mysql
      - ./conf.d:/etc/mysql/conf.d
    ports:
      - "127.0.0.1:3306:3306"

volumes:
  mysql_data:

services:
  mysql:
    image: mysql:8.0
    container_name: mysql_container
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: your_root_password
      MYSQL_DATABASE: my_project_db
      MYSQL_USER: my_project_user
      MYSQL_PASSWORD: my_project_password
    volumes:
      - mysql_data:/var/lib/mysql
      - ./conf.d:/etc/mysql/conf.d
    ports:
      - "127.0.0.1:3306:3306"

volumes:
  mysql_data:

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

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

3. Запускаем контейнер

cd /docker-containers/mysql
docker compose up -d

# Проверяем, что контейнер запущен
docker ps
docker logs mysql_container

# включаем автозапуск docker после перезагрузки VPS
sudo systemctl enable docker

cd /docker-containers/mysql
docker compose up -d

# Проверяем, что контейнер запущен
docker ps
docker logs mysql_container

# включаем автозапуск docker после перезагрузки VPS
sudo systemctl enable docker

При первом запуске контейнера Docker-образ MySQL сам создаёт базу и пользователя, а так-же дает пользователю все права на эту базу.

4. Импорт дампа в контейнер

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

docker exec -i mysql_container mysql -u my_project_user -p'my_project_password' my_project_db < /path/to/dump/backup-dump.sql

docker exec -i mysql_container mysql -u my_project_user -p'my_project_password' my_project_db < /path/to/dump/backup-dump.sql

Важно: это работает только при первом запуске, когда volume ещё пустой. Если контейнер уже запускался и данные есть — переменные игнорируются, база уже существует.

Проверям, что импорт прошел успешно.

docker exec -it mysql_container mysql -u my_project_user -p'my_project_password' my_project_db -e "SHOW TABLES;"

docker exec -it mysql_container mysql -u my_project_user -p'my_project_password' my_project_db -e "SHOW TABLES;"

В выводе должен быть список таблиц в базе данных my_project_db

5. Подключаем проект

Теперь нужно подключить проект к контейнеру с базой данных. Проекты могут использовать разные фреймворки и CMS.

Вариант А. Проект на WordPress.

Переходим в папку проекта, открываем файл wp-config.php, меняем значения констант.

define( 'DB_NAME', 'my_project_db' );
define( 'DB_USER', 'my_project_user' );
define( 'DB_PASSWORD', 'my_project_password' );
define( 'DB_HOST', '127.0.0.1:3306' );

define( 'DB_NAME', 'my_project_db' );
define( 'DB_USER', 'my_project_user' );
define( 'DB_PASSWORD', 'my_project_password' );
define( 'DB_HOST', '127.0.0.1:3306' );

Проверяем, что сайт открывается, нет ошибки подключения в базе данных.
После подключение проекта к контейнеру, СУБД на хостинге больше не нужна, можно удалить.

6. Добавление еще одной базы данных

Сейчас в контейнере создана только одна база данных для проекта my_project. Предположим, на этом же VPS расположен еще один проект, my_project2. Создадим в этом же контейнере еще одну БД для этого проекта. Для этого заходим в контейнер как пользователь root (пароль берем из MYSQL_ROOT_PASSWORD файла docker-compose.yaml ) и создаем нового пользователя и базу данных.

# Зайди в контейнер
docker exec -it mysql_container mysql -u root -p

# Внутри MySQL создай всё для второго сайта
CREATE DATABASE my_project2_db;
CREATE USER 'my_project2_user'@'%' IDENTIFIED BY 'my_project2_password';
GRANT ALL PRIVILEGES ON my_project2_db.* TO 'my_project2_user'@'%';
QUIT;

# Зайди в контейнер
docker exec -it mysql_container mysql -u root -p

# Внутри MySQL создай всё для второго сайта
CREATE DATABASE my_project2_db;
CREATE USER 'my_project2_user'@'%' IDENTIFIED BY 'my_project2_password';
GRANT ALL PRIVILEGES ON my_project2_db.* TO 'my_project2_user'@'%';
QUIT;

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

7. Хранение данных

Разбираемся, где лежат файлы MySQL на хост-машине.
В docker-compose.yaml указан именованный том mysql_data. По сути это папка на хосте, в которой лежат файлы MySQL. Так же указано, что на нее маппируется папка /var/lib/mysql в контейнере (стандартная папка с данными MySQL). Что бы узнать точное имя тома (папки) можно выполнить команду:

docker volume ls

# Вывод
# DRIVER    VOLUME NAME
# local     mysql-docker_mysql_data
# local     mysql_mysql_data

docker volume ls

# Вывод
# DRIVER    VOLUME NAME
# local     mysql-docker_mysql_data
# local     mysql_mysql_data

Видно, что точное имя тома mysql_mysql_data, так как к имени, указанному в опции volume добавляется имя папки, в которой лежит docker-compose.yaml, которое считается префиксом проекта.

Проверяем, где находится данный том

docker volume inspect mysql_mysql_data

# Вывод
# ....
# "Mountpoint": "/var/lib/docker/volumes/mysql_mysql_data/_data",
# "Name": "mysql_mysql_data",
# ....

docker volume inspect mysql_mysql_data

# Вывод
# ....
# "Mountpoint": "/var/lib/docker/volumes/mysql_mysql_data/_data",
# "Name": "mysql_mysql_data",
# ....

Mountpoint – это и есть путь к папке тома на хост-машине.
Том не зависит от контейнера, поэтому при остановке, перезапуске, удалении контейнера данные в базе данных будут сохранены.

Сделать дамп одной базы данных

docker exec mysql_container mysqldump \
  -u my_project_user -p'my_project_password' \
  my_project_db > my_project_db.sql

docker exec mysql_container mysqldump \
  -u my_project_user -p'my_project_password' \
  my_project_db > my_project_db.sql

Сделать дамп всех баз данных

docker exec mysql_container mysqldump \
  -u root -p'your_root_password' \
  --all-databases > backup_all.sql

docker exec mysql_container mysqldump \
  -u root -p'your_root_password' \
  --all-databases > backup_all.sql

Восстановление из дампа

docker exec -i mysql_container mysql \
  -u my_project_user -p'my_project_password' \
  my_project_db < backup.sql

docker exec -i mysql_container mysql \
  -u my_project_user -p'my_project_password' \
  my_project_db < backup.sql

8. Полезные команды docker

Напоминание:
1. mysql_container – это не зарезервированное слово, это имя контейнера, заданное в файле docker-compose.yaml (см. п2), может быть любым.
2. команда ‘docker’ может выполнятся из любой папки.
3. команда ‘docker compose’ выполняется из папки, в которой находится файл docker-compose.yaml (или указывается путь к файлу через флаг -f)

Сообщение Использование MySQL в контейнере Docker появились сначала на mcodex.

• Описание задачи и требования к проекту
• Начальная настройка проекта
• Пользователи для деплоя
• SSH-ключи
• Переменные Gitlab
• Структура проекта для CICD
• Переключение Nginx на новый проект
• Первый деплой через CICD
• Откат

Описание задачи и требования к проекту

Проект разрабатыватся на локальной машине, есть 2 сервера, dev и prodcution.
Стэк одинаковый: VPS Ubuntu/Nginx/PHP/MySQL/Laravel/Supervisor

Шаги в инструкции выполняются на обеих серверах. В результате получаем 2 развернутых версии проекта:
на dev-сервере (ветка develop) и production (ветка main).

После применения инструкции все дальнейшие загрузки обновлений происходят без ручного вмешательства на серверах, на dev-сервере – после пуша в ветку develop, на production – после пуша (или PR) в main и клика на кнопке деплоя (опциональный предохранитель).

Перед внедрением CICD, необходимо проверить следующие пункты:

1. На серверах есть полномочия sudo
2. В проекте есть тесты
3. В проекте есть публично доступный роут GET /health/ready, возвращает код 200.
4. Перед пушем в gitlab прогоняем тесты, линтер, pint.

Шаг 1. Начальная настройка проекта

Разворачиваем проекты на серверах из репозитория Gitlab вручную, без CICD, настраиваем Nginx, подключаем СУБД и т.д. Проверяем, что все работает.
Предположим, проект развернут в папке /var/www/my-project.com/classic-deploy

Сразу решаем, в какой папке будет расположен проект, разворачиваемый через CICD.
Допустим, он будет в папке /var/www/my-project.com/cicd-deploy

Шаг 2. Создаем пользователя для деплоя

2.1 На обеих серверах добавляем пользователя deployer. Через него Gitlab будет делать деплой.

sudo adduser deployer

sudo adduser deployer

2.2 Добавляем пользователя deployer в группу www-data

sudo usermod -aG www-data deployer

sudo usermod -aG www-data deployer

Проверяем, что добавлен в группу

groups deployer

groups deployer

в списке должна быть www-data

2.3 Добавляем возможность запуска от имени deployer определенных команд без пароля.
Для этого создаем файл конфига:

sudo visudo -f /etc/sudoers.d/deploy

sudo visudo -f /etc/sudoers.d/deploy

Добавляем в него строку (версию PHP при необходимости изменить):

deployer ALL=(ALL) NOPASSWD: /usr/bin/setfacl, /usr/bin/supervisorctl, /usr/bin/systemctl reload php8.5-fpm

deployer ALL=(ALL) NOPASSWD: /usr/bin/setfacl, /usr/bin/supervisorctl, /usr/bin/systemctl reload php8.5-fpm

Перед добавлением можно проверить, где находятся файлы

which supervisorctl
which systemctl
which setfacl

which supervisorctl
which systemctl
which setfacl

Проверяем валидность конфига файлов sudoers

visudo -c

visudo -c

Ожидаемый вывод

/etc/sudoers: parsed OK
/etc/sudoers.d/README: parsed OK
/etc/sudoers.d/deploy: parsed OK

/etc/sudoers: parsed OK
/etc/sudoers.d/README: parsed OK
/etc/sudoers.d/deploy: parsed OK

Шаг 3. Настраиваем SSH-ключи

3.1 Создаем ключ

Логинимся на сервер как пользователь deployer

ssh deployer@ip-address-here

ssh deployer@ip-address-here

Создаем новый ключ, без ключевой фразы, для дев-сервера используем префикс dev

ssh-keygen -t ed25519 -C "gitlab-deploy-prod"

ssh-keygen -t ed25519 -C "gitlab-deploy-prod"

Появляется папка /home/deployer/.ssh, в ней файлы ключа id_ed25519.pub и id_ed25519.
Имена файлов ключей лучше использовать дефолтные, иначе може возникнуть ошибка при подключении к Gitlab.

Задаем права на ключи

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
chmod 600 ~/.ssh/known_hosts

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
chmod 600 ~/.ssh/known_hosts

3.2 Добавляем публичный ключ в authorized_keys

Сначала проверяем, какой файл SSH-сервер реально читает для пользователя deployer

sudo sshd -T -C user=deployer | grep -Ei 'authorizedkeysfile|authorizedkeyscommand|pubkeyauth|allowusers|allowgroups|denyusers|denygroups'

sudo sshd -T -C user=deployer | grep -Ei 'authorizedkeysfile|authorizedkeyscommand|pubkeyauth|allowusers|allowgroups|denyusers|denygroups'

Получаем вывод

pubkeyauthentication yes
authorizedkeyscommand none
authorizedkeyscommanduser none
authorizedkeysfile .ssh/authorized_keys_123
pubkeyauthoptions none

pubkeyauthentication yes
authorizedkeyscommand none
authorizedkeyscommanduser none
authorizedkeysfile .ssh/authorized_keys_123
pubkeyauthoptions none

Смотрим значение authorizedkeysfile. Это файл в папке /home/deployer/.ssh
Может быть как дефолтным authorized_keys, так и переопределенным, как в примере выше

Добавляем ключ deployer’a:

cat ~/.ssh/id_ed25519.pub >> ~/.ssh/authorized_keys_123

cat ~/.ssh/id_ed25519.pub >> ~/.ssh/authorized_keys_123

Содержимое файла публичного ключа добавляем в ключи в репозитории проекта на Gitlab
Settings->Reposirory->Deploy keys->Add new key

В названии ключа указываем сервер и пользователя, что бы не путаться, например, “Production deployer”

После добавления найти ключ в вкладке "Privately accessible deploy keys" и нажать Enable. 
Ключ появится во вкладке "Enabled deploy keys"

Секретный ключ кодируем в base64

base64 -w 0 ~/.ssh/id_ed25519

base64 -w 0 ~/.ssh/id_ed25519

Полученный вывод пока копируем в текстовый файл, он понадобится в следующем шаге.

Проверяем, что ключ работает. Для этого в произвольной папке клонируем репозиторий.

mkdir ~/test
cd ~/test
git clone git@gitlab.com:your-project.git

mkdir ~/test
cd ~/test
git clone git@gitlab.com:your-project.git

После проверки удаляем тестовую папку, закрываем соединение под deployer.

Шаг 4. Задаем переменные Gitlab

В Gitlab, в папке проекта открываем Settings->CICD->Variables
Создаем переменные:
PROD_HOST – IP адрес, например, 123.1.123.12
PROD_BASE – путь к папке cicd-проекта, /var/www/my-project.com/cicd-deploy
PROD_APP_URL – публичный URL проекта, для запуска health check, например, https://my-project.com.
PROD_USER – deployer
PROD_SSH_PRIVATE_KEY_B64 – приватный ключ в формате base64 из предыдущего шага
Тип переменной – variable (default), visibility: visible, protect variable – выключено
Для дев-севера аналогично, но с префиксом DEV_

В результате в репозитории есть набор переменных

Результат на данном этапе:
Проект работает по прежнему из папки classic-deploy, на сервере добавлен пользователь deployer.

Шаг 5. Создаем структуру проекта для CICD

Допустим, проект, развернутый через CICD будет расположен в папке /var/www/my-project.com/cicd-deploy

В этом случае структура downtime-zero проекта будет следующей

/var/www/my-porject.com/cicd-deploy/
  ├── current -> releases/20260501-1430-abc1234 ← симлинк на активный релиз
  ├── releases/
  │ ├── 20260430-1731-2b5cc17/
  │ ├── 20260501-0900-69025b4/
  │ └── 20260501-1430-abc1234/ ← текущий
  └── shared/
    ├── .env
    └── storage/

/var/www/my-porject.com/cicd-deploy/
  ├── current -> releases/20260501-1430-abc1234 ← симлинк на активный релиз
  ├── releases/
  │ ├── 20260430-1731-2b5cc17/
  │ ├── 20260501-0900-69025b4/
  │ └── 20260501-1430-abc1234/ ← текущий
  └── shared/
    ├── .env
    └── storage/