Работа с новой архитектурой в Laravel 1118.06.2024 11:45

e8d8bdb8c4f8ab3b0bce685bbe1e65fe.jpg

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

Основная «киллер-фича» фреймворка Laravel версии 11 — «плоский код». Под капот убрано всё, что большинством разработчиков не используется, по сути являющееся «мусором». А также убраны некоторые действительно полезные вещи.

Изменения

То, что сразу бросается в глаза при установке проекта:

  1. Отсутствуют мидлвари;

  2. Отсутствуют некоторые сервис-провайдеры;

  3. Появился файл bootstrap/providers.php;

  4. Определение роутов, команд, мидлварь, ошибок и другого перенесено в файл bootstrap/app.php (раньше мидлвари определялись в файле app/Http/Kernel.php, эксепшены в app/Exceptions/Handler.php, крон-команды в app/Console/Kernel.php);

  5. Опция из настроек окружения для определения хранилища кэша переименована с CACHE_DRIVER на CACHE_STORE.

Теперь рассмотрим более детально и как мы с этим работаем.

bootstrap/app.php

Сказать по-правде, управление всем внутри одного конкретного файла, мягко говоря, очень неудобно, не функционально и не красиво. Поэтому для распределения мы используем invoke классы.

В конечном итоге, наш файл выглядит так: 

withMiddleware(new MiddlewareHandler())
    ->withExceptions(new ExceptionHandler())
    ->withSchedule(new ScheduleHandler())
    ->withCommands([__DIR__ . '/../app/Console/Commands'])
    ->withRouting(
        api: __DIR__ . '/../routes/api.php',
        commands: __DIR__ . '/../routes/console.php',
        apiPrefix: ''
    )->create();

Наше приложение работает исключительно как API и в нём нет таких понятий как web, blade, html, ts/js и т.п., за исключением страниц ошибок при попытке открыть их из адресной строки браузера. Вследствие чего и префикс api у всех роутов нам также не нужен, поэтому мы его «обнуляем».

Мидлвари

При чистой установке проекта Laravel предлагает описывать мидлвари в файле bootstrap/app.php, что является неудобным способом. Поэтому, при помощи invoke метода мы создали класс в привычном месте: 

 AuthPrivateMiddleware::class,
        'auth.public'   => AuthPublicMiddleware::class,
        'auth.internal' => AuthInternalMiddleware::class,
    ];

    public function __invoke(BaseMiddleware $middleware): BaseMiddleware
    {
        if ($this->aliases) {
            $middleware->alias($this->aliases);
        }

        return $middleware;
    }
}

Кроме алиасов, можно также работать с группами и всем, что умеют «обычные» мидлвари. Просто выглядит это немного иначе. В данном случае нужны только алиасы.

Таким образом, всё взаимодействие с мидлварями вынесено во внешний файл и легко читается любым разработчиком, работающим с Laravel.

Объявляем мы этот файл в методе withMiddleware файла bootstrap/app.php: 

withMiddleware(new MiddlewareHandler())
    // ...
    ->create();

Обработчик ошибок

Также как и с мидлварями, эксепшены лишились файла app/Exceptions/Handler.php, который мы также вернули в логически корректное место добавив свои объявления. В итоге, файл выглядит следующим образом: 

renderUnauthorized($exceptions);
        $this->renderNotFound($exceptions);

        $this->reportSentry($exceptions);

        return $exceptions;
    }

    protected function renderUnauthorized(BaseExceptions $exceptions): void
    {
        $exceptions->renderable(
            fn (AuthenticationException $e, ?Request $request = null) => $this->response(
                message: __('Unauthorized'),
                code: 401,
                asJson: $request?->expectsJson() ?? false
            )
        );
    }

    protected function renderNotFound(BaseExceptions $exceptions): void
    {
        $exceptions->renderable(
            fn (NotFoundHttpException $e, ?Request $request = null) => $this->response(
                message: __('Not Found'),
                code: 404,
                asJson: $request?->expectsJson() ?? false
            )
        );
    }

    protected function reportSentry(BaseExceptions $exceptions): void
    {
        $exceptions->reportable(
            fn (Throwable $e) => Integration::captureUnhandledException($e)
        );
    }

    protected function response(string $message, int $code, bool $asJson): Response
    {
        if ($asJson) {
            return response()->json(compact('message'), $code, options: $this->jsonFlags);
        }

        $this->registerErrorViewPaths();

        return response()->view($this->view($code), status: $code);
    }

    protected function view(int $code): string
    {
        return view()->exists('errors::' . $code) ? 'errors::' . $code : 'errors::400';
    }

    protected function registerErrorViewPaths(): void
    {
        View::replaceNamespace(
            'errors',
            collect(config('view.paths'))
                ->map(fn (string $path) => "$path/errors")
                ->push($this->vendorViews())
                ->all()
        );
    }

    protected function vendorViews(): string
    {
        return __DIR__ . '/../../vendor/laravel/framework/src/Illuminate/Foundation/Exceptions/views';
    }
}

Пути к view фалам переопределены для того, чтобы мы могли отображать переведённые расшифровки ошибок, например,»404 | Не найдено» вместо »404 | Not Found» для российской локализации.

Например, файл resources/views/errors/404.blade.php содержит следующий код: 

@extends('errors::minimal')

@section('title', __('http-statuses.404'))
@section('code',  404)
@section('message', __('http-statuses.404'))

Объявляем мы этот файл в методе withException файла bootstrap/app.php: 

withExceptions(new ExceptionHandler())
    // ...
    ->create();

Выполнение заданий по расписанию (schedule)

Внезапно в Laravel 11 определение запуска заданий по расписанию, которые принято называть «кроном» (cron), стали… барабанная дробь… РОУТАМИ!

Да, Вы не ослышались. Согласно новым правилам запуск консольных команд определяется в файле routes/console.php.

И нам с этим нужно срочно что-то делать начиная с того, что в нашей команде принято файл routes/console.php исключать из репозитория, так как его цель заключается в хранении личных наборов команд разработчика не беспокоясь о том, что она может случайно попасть в репозиторий. Такое постоянно случалось до введения этой практики, когда мы создавали новые «dev» классы в папке app/Console/Commands.

Поэтому создаём новый старый класс App\Console\Handler: 

command(PruneStaleTagsCommand::class)->hourly();

        // ...
    }
}

Объявляем мы этот файл в методе withSchedule файла bootstrap/app.php: 

withSchedule(new ScheduleHandler())
    // ...
    ->create();

Консольные команды

Инициализация консольных команд происходит в методе withCommands файла bootstrap/app.php. Здесь нужно передать массив абсолютных путей к директориям. Таким образом, мы просто передаём параметр на папку app/Console: 

withCommands([__DIR__ . '/../app/Console/Commands'])
    // ...
    ->create();

Здесь ничего сложного. Просто объявили и из консоли уже можно вызывать php artisan .

Маршрутизация

Помимо прочего, новая версия Laravel также лишилась сервис-провайдера RouteServiceProvider и теперь объявлять маршруты нужно непосредственно в файлах папки routes. Так как у нас нет web зоны, мы решили оставить файл routes/api.php, добавив в него вызов групп: 

middleware('auth.private')
    ->name('private.')
    ->prefix('v1/private')
    ->group(__DIR__ . '/api/private.php');

app('router')
    ->middleware('auth.public')
    ->name('public.')
    ->prefix('v1/public')
    ->group(__DIR__ . '/api/public.php');

app('router')
    ->middleware('auth.internal')
    ->name('internal.')
    ->prefix('v1/internal')
    ->group(__DIR__ . '/api/internal.php');

Сервис-провайдеры

Несмотря на то, что объявление сервис-провайдеров в новой версии фреймворка было вынесено в файл bootstrap/providers.php, старое расположение всё же работает, и работает по принципу array_merge.

Например, наше приложение имеет русскую fallback локализацию, но Laravel не умеет переводить текст из json файлов на неё. То есть условный __('Whoops!') отдаст как Whoops! вместо Упс!. Решает эту проблему пакетное решение JSON Fallback, но речь не столько о нём, сколько о принципе его подключения.

Так вот, для работы этого пакета нужно заменить дефолтный сервис-провайдер Illuminate\Translation\TranslationServiceProvider на другой. В случае с новой структурой приложения сделать это попросту невозможно — файл bootstrap/providers.php возвращает массив строк, где строка — прямая ссылка на сервис-провайдер. А нам мало того, что нужно заменить провайдер, дак ещё и заменить дефолтный, то есть тот, который находится где-то под капотом. И что делать? — спросите. Вот здесь нам на помощь и приходит новая старая опция providers в файле config/app.php. Просто добавляем её, объявляя дефолтные сервис-провайдеры, и всё. Приложение дальше само возьмёт их, сделает нужные подмены и подгрузит содержимое файла bootstrap/providers.php, следствием чего станет корректная работа приложения с заменяемыми сервис-провайдерами.

// config/app.php

 env('APP_NAME', 'Laravel'),

    // ...

    'providers' => ServiceProvider::defaultProviders()->replace([
        BaseTranslationServiceProvider::class => JsonTranslationServiceProvider::class,
    ])->toArray(),
];

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

routes/console.php

Данный файл каждый разработчик использует в своих личных целях и он исключён из попадания в репозиторий.

Аргумент commands метода withRouting в файле bootstrap/app.php позволяет принимать в качестве значения путь, который под капотом валидируется на существование. Таким образом, нам не нужно самостоятельно это делать.

В итоге, получаем следующее объявление: 

withRouting(
        api: __DIR__ . '/../routes/api.php',
        commands: __DIR__ . '/../routes/console.php',
        apiPrefix: ''
    )->create();

И убеждаемся в наличии строчки /routes/console.php в файле .gitignore, а также в отсутствии файла в самом репозитории.

Если какой-либо файл попал в репозиторий, хотя должен игнорироваться и правило на него описано в файле .gitignore, удалите файл и создайте коммит. Уже записанные в репозиторий файлы игнорируют эти параметры.

Заключение

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

  • Нелогичность размещения объявлений управления;

  • Непонимание разработчиков при работе с органами управления;

  • Перегрузка роутов кроном;

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

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

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

Всех благ и удачных проектов!

© Habrahabr.ru