Перейти к содержимому
Документация · Интеграции

Laravel

Middleware для любого метода, а не только для маршрутов. goaop/goaop-laravel-bridge 2.0 подключает behaviors к вашим классам, а контейнер, конфигурация и Artisan из Laravel делают остальное.

Перевод с английского. Эталоном считается английская версия страницы. Читать оригинал

Middleware (промежуточный слой) — одна из лучших идей Laravel. Запрос проходит через стек небольших классов, и каждый добавляет что-то одно (аутентификацию, ограничение частоты, сессию), не трогая ваш контроллер. Мост (bridge) goaop/goaop-laravel-bridge 2.0 переносит эту идею на каждый метод и каждое свойство вашего приложения — публичные, защищённые и приватные. Вы один раз пишете behavior (поведение), указываете, где он применяется, и он выполняется вокруг этих вызовов как динамический middleware: в сервисах, actions, jobs и любом другом классе в app/.

app/Services/OrderService.php
use App\Attributes\Transactional;
final class OrderService
{
public function __construct(private readonly Inventory $inventory) {}
#[Transactional]
public function place(Cart $cart): Order
{
$order = Order::create(['customer_id' => $cart->customerId]);
$order->lines()->createMany($cart->lines());
$this->inventory->reserve($cart);
return $order;
}
}
app/Behaviors/TransactionalBehavior.php
namespace App\Behaviors;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
use Illuminate\Support\Facades\DB;
final class TransactionalBehavior implements Aspect
{
#[Around('@execution(App\Attributes\Transactional)')]
public function inTransaction(MethodInvocation $invocation): mixed
{
return DB::transaction(fn () => $invocation->proceed());
}
}

Вот и весь приём. Если вы писали handle($request, $next) для middleware, вы его уже знаете: $invocation->proceed() — это ваш $next($request). Каждый метод с #[Transactional] теперь фиксируется или откатывается как единое целое, а в OrderService по-прежнему только бизнес-логика. Не нужны ни базовый класс, ни интерфейс, ни декоратор, ни вызов app()->extend().

  • Устанавливается как любой другой пакет. composer require — и package discovery регистрирует сервис-провайдер. Один публикуемый файл конфигурации, config/go_aop.php, с переопределениями через переменные окружения GOAOP_*.
  • Behavior classes (классы поведений) — это сервисы контейнера. Контейнер Laravel создаёт каждый behavior class, когда один из его behaviors выполняется впервые. Работает внедрение через конструктор, а также фасады, config() и любой сервис, который связывает ваше приложение.
  • Регистрируйте их там же, где и всё остальное. Укажите класс в конфигурации или пометьте сервис тегом goaop.aspect в сервис-провайдере — так пакет может добавить собственные behaviors.
  • Работу для продакшена делает Artisan. php artisan aop:warmup собирает кеш при деплое, при желании в параллельных воркерах. Команда встраивается в уже существующий деплой, после composer install и php artisan optimize. php artisan about показывает расположение кеша и режим отладки.
  • Никакого шага сборки при разработке. С включённым debug изменённый класс перекомпилируется при следующем запросе, а точки останова работают в ваших исходных файлах.

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

  • Он есть у каждого экземпляра. Объекты из контейнера и объекты, созданные через new, ведут себя одинаково. Подсказки типов, instanceof и имя класса не меняются, потому что объекта-обёртки не существует.
  • Подходит любой метод. Приватные, защищённые, final и статические методы, а также методы классов final и readonly (Перехват чего угодно).
  • И свойства тоже. Чтение и запись публичных, защищённых и приватных свойств, включая продвинутые через конструктор, через нативные хуки свойств PHP 8.4: access(private App\Domain\Order->status) или @access(App\Attributes\Audited) (Behaviors на свойствах).
  • Одно правило может покрыть пространство имён. execution(public App\Services\**->*(*)) выбирает каждый публичный метод внутри App\Services, включая классы, которые вы добавите в следующем месяце (см. Matching rules — правила выбора).
  • Затраты невелики. Методы и свойства без behaviors ничего дополнительно не стоят. Метод или свойство с behavior платит меньше 1 мкс за вызов (измеренные затраты).
  • Это обычный PHP. Ни расширения PECL, ни eval(). Скомпилированные классы — обычные файлы .php в storage/framework/aop, так что их можно прочитать (Чистый PHP).
  • PHP 8.4 или новее
  • Laravel 12 или 13
  • goaop/framework ^4.0 (behaviors объявляются атрибутами), устанавливается вместе с мостом
Окно терминала
composer require goaop/goaop-laravel-bridge

Package discovery регистрирует сервис-провайдер автоматически. Если хотите изменить конфигурацию, опубликуйте её:

Окно терминала
php artisan vendor:publish --tag=goaop-config

Behavior class (в API — aspect, аспект) — это обычный класс, реализующий Go\Aop\Aspect. Каждый его публичный метод с #[Before], #[After], #[Around] или #[AfterThrowing] — это один behavior, а строка в этом атрибуте — его matching rule (правило выбора; в API — pointcut, срез): она говорит, где выполняется behavior.

  1. Создайте атрибут, чтобы помечать методы, или пропустите этот шаг и выбирайте методы по имени (см. следующий раздел).

    app/Attributes/Transactional.php
    namespace App\Attributes;
    use Attribute;
    #[Attribute(Attribute::TARGET_METHOD)]
    final class Transactional {}
  2. Напишите behavior class. TransactionalBehavior из начала этой страницы уже готов. #[Around] выполняет behavior вместо метода, а @execution(App\Attributes\Transactional) выбирает каждый метод с этим атрибутом.

  3. Зарегистрируйте behavior class в config/go_aop.php:

    config/go_aop.php
    'aspects' => [
    App\Behaviors\TransactionalBehavior::class,
    ],
  4. Пометьте метод атрибутом #[Transactional] и вызовите его. Следующий запрос выполнит его внутри транзакции.

Behavior не нужен атрибут на целевом методе. Matching rule может выбирать методы по имени, пространству имён или видимости, так что целый слой приложения получает behavior без каких-либо изменений в его классах:

app/Behaviors/ServiceTimingBehavior.php
namespace App\Behaviors;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
use Go\Lang\Attribute\Before;
use Illuminate\Support\Facades\Log;
final class ServiceTimingBehavior implements Aspect
{
#[Before('execution(public App\Services\**->*(*))')]
public function logCall(MethodInvocation $invocation): void
{
Log::debug('Calling ' . $invocation->getMethod()->getName());
}
#[Around('execution(public App\Services\PaymentService->charge(*))')]
public function measureCharge(MethodInvocation $invocation): mixed
{
$start = hrtime(true);
try {
return $invocation->proceed();
} finally {
Log::info('charge() took ' . (hrtime(true) - $start) / 1e6 . ' ms');
}
}
}

logCall() выполняется перед каждым публичным методом внутри App\Services. measureCharge() оборачивает один метод и замеряет его время, в том числе когда он выбрасывает исключение. Четыре атрибута, call context (контекст вызова, $invocation) и полный синтаксис правил описаны на странице Поведения и правила выбора. Полные пошаговые примеры — на страницах Кеширование результатов и Логирование вызовов.

Вам никогда не нужно самостоятельно передавать behavior classes движку. На этапе boot, после того как все сервис-провайдеры зарегистрированы и до того, как запустится код приложения, мост собирает их из двух источников.

Список в конфигурации. Укажите класс в config/go_aop.php, как в шагах выше. Указанный класс регистрируется сразу при старте ядра (kernel), без загрузки самого класса. Контейнер Laravel создаёт его при первом вызове одного из его behaviors, поэтому behavior class может зависеть от сервисов, которые появляются только после полной загрузки приложения. Запрос, в котором не выполняется ни один из его behaviors, его вообще не создаёт.

Тег goaop.aspect. Пометьте сервис в одном из ваших сервис-провайдеров:

app/Providers/AppServiceProvider.php
use App\Behaviors\ServiceTimingBehavior;
use Psr\Log\LoggerInterface;
// in register()
$this->app->singleton(ServiceTimingBehavior::class, function ($app) {
return new ServiceTimingBehavior($app->make(LoggerInterface::class));
});
$this->app->tag([ServiceTimingBehavior::class], 'goaop.aspect');

Используйте тег, когда behavior class требует нетривиального создания или когда пакет добавляет behavior classes, не трогая вашу конфигурацию. Сервисы с тегом создаются при загрузке провайдера моста, потому что перечислить тег Laravel можно только создав его сервисы. Для behavior classes с тяжёлыми или зависящими от загрузки конструкторами предпочитайте список в конфигурации.

Оба источника можно сочетать; дубликаты регистрируются один раз. Найденный класс, который не реализует Go\Aop\Aspect, приводит к исключению с понятным описанием. Контейнер Laravel подключается к контейнеру ядра как его делегат PSR-11, так что behaviors и фабрики behavior classes могут получать через него сервисы приложения.

Основные опции в config/go_aop.php. Каждую можно переопределить через окружение.

Опция По умолчанию Назначение
debug GOAOP_DEBUG → APP_DEBUG Перекомпиляция при изменении исходников, точки останова в исходных файлах; в продакшене держите выключенным
appDir base_path() Корневой каталог, который может затрагивать компилятор
cacheDir storage_path('framework/aop') (GOAOP_CACHE_DIR) Где кешируются скомпилированные исходники и прокси
cacheFileMode 0770 (GOAOP_CACHE_PERMISSIONS, восьмеричные цифры, например "770") chmod для файлов кеша
parsedFilesLimit 100 (GOAOP_PARSED_FILES_LIMIT) Сколько разобранных исходных файлов (около 0,2 МБ каждый) хранится в памяти при компиляции; значение по умолчанию для aop:warmup --cached-files
includePaths [app_path()] Компилируются только эти каталоги
excludePaths [] Эти каталоги не компилируются никогда
features 0 (GOAOP_FEATURES) Битовая маска флагов Go\Aop\Features: INTERCEPT_INCLUDES = 4, PREBUILT_CACHE = 64, PARTIAL_REFLECTION = 256
aspects [] Behavior classes для регистрации

Behaviors на вызовы функций и на создание объектов управляются своими matching rules и не требуют флага. php artisan about показывает текущее расположение кеша фреймворка и режим отладки.

Окно терминала
php artisan aop:warmup

Без прогрева каждый класс компилируется при первой загрузке. Запускайте aop:warmup при деплое, чтобы скомпилировать их все заранее; это рекомендуется при выключенном debug. Команда завершается с ненулевым кодом, если файл не компилируется, так что скрипт деплоя останавливается, а не выкатывает неполный кеш. Передайте --fail-fast, чтобы остановиться на первой ошибке.

Окно терминала
php artisan aop:warmup --workers=8
php artisan aop:warmup --cache-dir=/srv/app/releases/next/storage/framework/aop
php artisan aop:warmup --preload
  • --workers=N компилирует в параллельных рабочих процессах. Каждый воркер — это ваш собственный artisan, поэтому он стартует с тем же окружением, конфигурацией и behavior classes.
  • --cache-dir=DIR собирает кеш нового релиза рядом с работающим. Собранный таким образом кеш полон и не зависит от расположения.
  • --preload записывает скрипт opcache.preload: _preload.php в собираемом каталоге кеша или файл, указанный как --preload=FILE.

Чтобы поставлять скомпилированные скрипты вместе с образом контейнера, прогрейте opcache.file_cache после прогрева и после php artisan optimize, в финальном образе:

Окно терминала
php artisan optimize
mkdir -p /var/cache/opcache && php -d opcache.enable_cli=1 -d opcache.file_cache_only=1 \
-d opcache.file_cache=/var/cache/opcache \
artisan aop:warmup-opcache --file-cache=/var/cache/opcache
Окно терминала
composer install --no-dev --optimize-autoloader # runs package:discover, with an empty framework cache
php artisan optimize # the cached configuration carries GOAOP_FEATURES
php artisan aop:warmup

С GOAOP_FEATURES=64 (PREBUILT_CACHE) запрос никогда ничего не компилирует. Класс внутри include paths, которого нет в кеше, приводит к WeavingException, поэтому запускайте aop:warmup при каждом деплое. Команды кеша Laravel (package:discover, optimize, optimize:clear, а также команды кеширования и очистки config, event, route и view) не обслуживают запросы, поэтому загружают классы из их исходников. Вот почему порядок выше работает.

После кеширования конфигурации env() больше не читается. Запускайте optimize (или config:cache) с продакшен-окружением, включая GOAOP_FEATURES. Полный чек-лист — на странице Продакшен и производительность.

  • Compile step (этап компиляции) начинается в самом начале этапа boot. Классы, загруженные раньше (очень ранний bootstrap-код, внутренности register() других пакетов, ваши собственные сервис-провайдеры), behaviors получить не могут.
  • Рассматриваются только классы внутри appDir и includePaths. Код из vendor не компилируется.
  • Исключите обработчики исключений через excludePaths: при фатальной ошибке скомпилированный обработчик может не загрузиться из холодного кеша.

© 2026 Alexander Lisachenko