Сервис-контейнер, провайдеры, свои artisan-команды и планировщик

[oleg_php]

К шестнадцатой главе вы уже не раз пользовались сервис-контейнером, просто не называли его по имени. Каждый раз, когда Laravel сам подставлял Request в метод контроллера или CartService в конструктор, работал именно он. Пора разобрать механизм явно, а заодно научиться писать свои artisan-команды и вешать их на расписание. Примеры проверены на Laravel 12 и PHP 8.3.

Контейнер и привязки:

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

Код: Выделить всё

// app/Providers/AppServiceProvider.php
use App\Services\Sms\SmsSender;
use App\Services\Sms\SmscClient;

public function register(): void
{
    $this->app->singleton(SmsSender::class, function ($app) {
        return new SmscClient(
            login: config('services.smsc.login'),
            password: config('services.smsc.password'),
        );
    });
}

Способов привязки три. bind() создаёт новый объект при каждом resolve. singleton() держит один объект на весь процесс. scoped() даёт один объект на время одного HTTP-запроса или job'а, потом контейнер его выбрасывает. Под классическим PHP-FPM singleton и scoped ведут себя одинаково, процесс и так живёт ровно один запрос. Под Octane или в воркере очереди разница принципиальная: singleton с состоянием запроса (текущий пользователь, корзина) протечёт в соседний запрос. Правило: всё, что хранит состояние запроса, объявляйте через scoped, чистые stateless-сервисы через singleton. Есть ещё контекстные привязки (when, needs, give) на случай, когда одному конкретному классу нужна другая реализация интерфейса, ищите в документации contextual binding.

Провайдеры:

Привязкам нужно место регистрации, и это сервис-провайдеры. Пока проект маленький, всё живёт в AppServiceProvider, а когда он распухает, домен выносят в отдельный класс:

Код: Выделить всё

php artisan make:provider SmsServiceProvider

На Laravel 11 и новее команда сама допишет класс в bootstrap/providers.php, руками ничего регистрировать не нужно. У провайдера два метода с жёстким разделением ролей. В register() только привязки. В boot() контейнер уже собран целиком, здесь регистрируют view-композеры, обсерверы моделей, макросы.

Свои artisan-команды:

Код: Выделить всё

// php artisan make:command PruneStaleCarts
class PruneStaleCarts extends Command
{
    protected $signature = 'carts:prune {--days=14 : Удалять корзины старше N дней}';

    protected $description = 'Чистит брошенные корзины';

    public function handle(CartService $carts): int
    {
        $deleted = $carts->pruneOlderThan((int) $this->option('days'));

        $this->info("Удалено корзин: {$deleted}");

        return self::SUCCESS;
    }
}

Файл лежит в app/Console/Commands и подхватывается автоматически, никаких списков заполнять не надо. handle() резолвится через контейнер, поэтому зависимости объявляем прямо в сигнатуре метода. Возвращайте self::SUCCESS или self::FAILURE, по коду выхода мониторинг поймёт, что задача упала. Если команду нельзя запускать в два экземпляра параллельно, добавьте классу интерфейс Illuminate\Contracts\Console\Isolatable, и у команды появится флаг --isolated.

Планировщик:

С Laravel 11 консольного Kernel больше нет, расписание объявляется прямо в routes/console.php:

Код: Выделить всё

use Illuminate\Support\Facades\Schedule;

Schedule::command('carts:prune --days=30')->dailyAt('03:10');

Schedule::command('reports:daily')
    ->dailyAt('07:00')
    ->timezone('Europe/Moscow')
    ->withoutOverlapping(30)
    ->onOneServer()
    ->appendOutputTo(storage_path('logs/reports.log'));

На сервере нужна ровно одна строка в cron. Она дёргает планировщик каждую минуту, а тот сам решает, чьё время пришло:

Код: Выделить всё

* * * * * cd /var/www/shop && php artisan schedule:run >> /dev/null 2>&1

Локально cron не нужен, php artisan schedule:work крутит тот же цикл прямо в терминале. Что и когда запустится, показывает php artisan schedule:list.

Типичные грабли:

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

Забытая строка в cron. Планировщик сам по себе не работает. Симптом классический: локально через schedule:work всё летает, на проде тишина.

withoutOverlapping() и onOneServer() держат блокировки в кэше, нужен драйвер с поддержкой локов (redis, database, memcached). И аккуратнее с php artisan cache:clear на проде: он снесёт и активные локи тоже.

Время. Cron живёт в таймзоне сервера, планировщик по умолчанию считает в app.timezone, а это чаще всего UTC. Не угадывайте, задавайте timezone() явно у задач, привязанных к человеческому времени.

Долгие задачи. По умолчанию задачи одного запуска идут последовательно, и отчёт на двадцать минут задержит всё остальное. Вешайте runInBackground(), а ещё лучше пусть команда просто кидает job в очередь из главы 10.

Итог: контейнер развязывает код от конкретных реализаций, провайдеры дают привязкам дом, команды и планировщик закрывают фоновую рутину без сторонних демонов. В следующей, последней главе доведём проект до продакшена: деплой, тот самый cron, supervisor для воркеров и обзор фронтенд-стека (Vite, Livewire, Inertia).

[pythonninja]

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

[ansibleandy]

аккуратнее с php artisan cache:clear на проде: он снесёт и активные локи тоже

плюсую, у нас так дважды стартанул импорт прайсов на 40к позиций. админ дернул cache:clear посреди деплоя, лок от withoutOverlapping испарился, второй инстанс радостно поехал. вынесли локи в отдельный redis-стор и спим спокойно

[lonelyburnout]

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

[ansible_andy]

А чем плох schedule:work на проде, если завернуть его в supervisor? По сути тот же цикл, зато с crontab возиться не надо.