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

Symfony

Интеграция с Symfony через goaop/goaop-symfony-bundle 4.0: автоконфигурация behavior classes, панель в веб-профилировщике и прогрев кеша.

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

Бандл goaop/goaop-symfony-bundle 4.0 подключает behaviors (поведения) к вашим сервисам в момент их загрузки. Ни базовые классы, ни декораторы не нужны.

namespace App\Aspect;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
use Psr\Log\LoggerInterface;
final class TimingAspect implements Aspect
{
public function __construct(private readonly LoggerInterface $logger) {}
#[Around('execution(public App\Service\**->*(*))')]
public function measure(MethodInvocation $invocation): mixed
{
$start = hrtime(true);
try {
return $invocation->proceed();
} finally {
$this->logger->info('{method} took {ms} ms', [
'method' => (string) $invocation,
'ms' => (hrtime(true) - $start) / 1e6,
]);
}
}
}

Это и есть вся интеграция. Класс реализует Go\Aop\Aspect, поэтому автоконфигурация регистрирует его как behavior class (класс поведений), а автовайринг передаёт ему логгер. Начиная со следующего запроса, время выполнения каждого публичного метода каждого класса внутри App\Service замеряется.

  • PHP 8.4 или новее
  • Symfony 7.4 или 8.x
  • goaop/framework ^4.0 (behaviors объявляются атрибутами)
Окно терминала
composer require goaop/goaop-symfony-bundle

Зарегистрируйте бандл первой записью в config/bundles.php:

config/bundles.php
return [
Go\Symfony\GoAopBundle\GoAopBundle::class => ['all' => true],
Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
// ...
];

Compile step (этап компиляции) применяется только к классам, загруженным после инициализации ядра (kernel), а бандлы загружаются в порядке регистрации. Бандл следит за этим сам: если он не первый, сборка контейнера падает с понятным сообщением.

Файл конфигурации необязателен. С настройками по умолчанию, показанными ниже, бандл компилирует каталог src/ в режиме ядра и включает собранный заранее кеш в продакшене:

config/packages/go_aop.yaml
go_aop:
include_paths: ['%kernel.project_dir%/src']
when@prod:
go_aop:
features: [PREBUILT_CACHE]

bin/console config:dump-reference go_aop выводит полный справочник. Все опции со значениями по умолчанию:

config/packages/go_aop.yaml
go_aop:
# Development mode: changed sources and behavior classes are compiled again on the next request,
# breakpoints work in the original files. Keep it off in production.
debug: '%kernel.debug%'
# Application root: only files below it can be compiled, cache paths mirror source paths relative to it.
app_dir: '%kernel.project_dir%'
# Directory for generated sources, proxies and behavior caches. Anchor it on %kernel.cache_dir%
# or %kernel.build_dir% so that cache:clear and cache:warmup manage it.
cache_dir: '%kernel.cache_dir%/aop'
# Permissions of the cache files: an octal literal (0o770), an octal string ("0770") or an integer.
# Defaults to 0770 minus the umask.
cache_file_mode: ~
# Directories that are compiled. Keep the list narrow: compiling vendor code is slow and rarely needed.
include_paths: ['%kernel.project_dir%/src']
# Directories below the include paths that are never compiled (the cache directory and the
# framework itself are always excluded).
exclude_paths: []
# Number of parsed source files the compiler keeps in memory (about 0.2 MB each).
parsed_files_limit: 100
# Framework features, by the name of the Go\Aop\Features constant:
# PREBUILT_CACHE trust the deployed cache completely, never check or write it at runtime
# INTERCEPT_INCLUDES route include/require in compiled files through the compiler (legacy code)
# PARTIAL_REFLECTION compile classes whose parent class, interface or trait Composer can not
# locate, with their own members
features: []
# Kernel class; extend Go\Symfony\GoAopBundle\Kernel\AspectSymfonyKernel to customize
# the transformation pipeline.
kernel_class: Go\Symfony\GoAopBundle\Kernel\AspectSymfonyKernel
# Compile every file below the include paths during cache:warmup and cache:clear.
cache_warmer: true
# Doctrine ORM integration, enabled automatically when DoctrineBundle is registered.
doctrine: ~

Переменные окружения работают как везде в Symfony, например debug: '%env(bool:GOAOP_DEBUG)%'. Matching rules (правила выбора) для функций и initialization() не требуют флага возможностей: они сами включают нужный им механизм.

Behavior class — это обычный автоматически связываемый (autowired) сервис. Автоконфигурация регистрирует каждый сервис, реализующий Go\Aop\Aspect. Без автоконфигурации пометьте сервис тегом goaop.aspect:

services:
Acme\Audit\AuditAspect:
tags: [goaop.aspect]

Behavior class — синглтон: если зарегистрировать его как два сервиса, компиляция контейнера завершится ошибкой.

Компилятору нужны только сами behavior classes. Контейнер Symfony создаёт behavior class, когда один из его behaviors выполняется впервые, и никогда — во время compile step или прогрева кеша. Контейнер ядра (AspectContainer) также делегирует контейнеру Symfony, поэтому $aspectContainer->get(LoggerInterface::class) работает. Go\Core\AspectKernel и Go\Core\AspectContainer доступны для автовайринга, а goaop.aspect_kernel — публичный сервис.

Прежде чем полагаться на behavior class, проверьте, что он выбирает:

Окно терминала
bin/console debug:aspect # behavior classes with their rules and behaviors
bin/console debug:advisor --advisor='App\Aspect\TimingAspect->measure' # the methods one behavior matches

В режиме отладки классы внутри include paths компилируются при первой загрузке и перекомпилируются, когда меняется их исходник или behavior class.

Если установлен symfony/web-profiler-bundle, панель инструментов показывает число behavior classes. Панель Go! AOP перечисляет:

  • behavior classes с их advisors, атрибутами behaviors и matching rules;
  • скомпилированные классы, загруженные во время запроса, вместе с их файлами прокси;
  • классы внутри include paths, загруженные до инициализации ядра (панель становится жёлтой);
  • действующую конфигурацию ядра.

Третий список помогает найти бандл, который загружается раньше GoAopBundle, и объясняет тот единственный запрос, который пересобрал контейнер. Этому запросу приходится загружать классы сервисов до загрузки бандла, поэтому один раз они выполняются без своих behaviors. Следующий запрос работает уже полностью скомпилированным. На деплой это не влияет, потому что cache:clear и cache:warmup собирают контейнер и кеш фреймворка вместе.

Бандл также отключает в Symfony .container.dumper.inline_class_loader, если ваша конфигурация не задаёт эту опцию явно. Она подключает файлы сервисов напрямую, в обход загрузчика классов, а значит, и в обход compile step.

Окно терминала
composer install --no-dev --optimize-autoloader # runs cache:clear through the auto-scripts
# or explicitly
bin/console cache:clear
bin/console cache:warmup

cache:clear и cache:warmup компилируют всё приложение через cache warmer. cache:clear собирает новый кеш рядом с работающим и затем переименовывает его. Warmer собирает кеш фреймворка в этом новом каталоге с нуля, так что привычные шаги деплоя менять не нужно. Прогрев завершается с ошибкой, если файл не компилируется, и деплой останавливается, а не выкатывает неполный кеш. Запустите cache:warmup:aop --fail-fast -vvv, чтобы увидеть файл и ошибку.

Команды фреймворка регистрируются в консоли вашего приложения. Они работают с запущенным ядром, поэтому аргумент loader из vendor/bin/aspect не указывается.

Команда Назначение
cache:warmup:aop [--fail-fast] [--cache-dir=DIR] [--cached-files=N] [--preload[=FILE]] Компилирует в кеш каждый файл внутри include paths. Завершается с ошибкой, если файл не компилируется. --preload дополнительно записывает скрипт opcache.preload для этого кеша.
cache:warmup:opcache [--file-cache=DIR] [--entry=FILE] Прогревает файловый кеш OPcache (opcache.file_cache) кешем фреймворка и приложением. Запускайте в финальном образе.
debug:aspect [--aspect=FQCN] Выводит behavior classes с их matching rules и advisors.
debug:advisor [--advisor=ID] Выводит advisors; с --advisor — то, что выбирает этот advisor.
debug:weaving [-v] Компилирует приложение дважды и сообщает о различающихся прокси, что указывает на недетерминированный behavior class.

cache:warmup:aop --workers=N здесь компилирует в одном процессе: его рабочим процессам пришлось бы загружать ядро через загрузочный файл, а у консоли приложения такого файла нет.

config/packages/go_aop.yaml
when@prod:
go_aop:
features: [PREBUILT_CACHE]

С PREBUILT_CACHE во время выполнения пропускаются все проверки файловой системы, связанные с кешем, и ничего не компилируется и не пишется в каталог кеша. Класс внутри include paths, о котором кеш не знает, вызывает WeavingException («… is missing from the prebuilt AOP cache …»). Пересобирайте кеш при каждом деплое. Это рекомендуемая настройка для продакшена, и с ней работают файловые системы только для чтения и неизменяемые образы.

Если ваш kernel.build_dir отличается от kernel.cache_dir, привяжите кеш фреймворка к каталогу, который собирается при деплое: cache_dir: '%kernel.build_dir%/aop'.

Для предзагрузки OPcache подключайте скрипт предзагрузки кеша фреймворка раньше файла предзагрузки контейнера:

config/preload.php
if (is_file($aop = dirname(__DIR__).'/var/cache/prod/aop/_preload.php')) {
require $aop;
}
if (is_file($container = dirname(__DIR__).'/var/cache/prod/App_KernelProdContainer.preload.php')) {
require $container;
}

В продакшен-режиме cache warmer записывает _preload.php в каталог кеша фреймворка. Поправьте путь, если cache_dir не равен %kernel.cache_dir%/aop. Не загружайте ядро в config/preload.php: это падает с «Cannot redeclare class». Подробнее о продакшен-сборках — на странице Продакшен и производительность.

Если зарегистрирован DoctrineBundle или вы задали doctrine: true, бандл:

  • заменяет сканирование каталогов в каждом драйвере атрибутов ORM на Go\Bridge\Doctrine\WovenEntityClassLocator, который загружает сущности через загрузчик классов, так что они сохраняют свои behaviors;
  • регистрирует Go\Bridge\Doctrine\MetadataLoadInterceptor как слушатель loadClassMetadata, который при загрузке метаданных сообщает о перехваченном свойстве сущности, если нативные ленивые объекты выключены.

Чтобы сущности компилировались, они должны лежать внутри include path. Тогда их behaviors применяются независимо от того, создаёт их ваш код или гидрирует ORM. Оба класса описаны на странице Doctrine ORM.

  • Behavior не применяется. Сначала запустите debug:advisor --advisor=...: команда показывает, что выбирает matching rule. Затем проверьте, что класс лежит внутри include path и не загружается раньше бандла (панель профилировщика, classes loaded before weaving). Код из vendor компилируется, только если его каталог указан в include paths.

  • «Class … is missing from the prebuilt AOP cache». Деплой выкатил код, для которого кеш не собирался. Выполните bin/console cache:clear (или cache:warmup) после того, как код окажется на месте.

  • «Circular reference detected for the aspect …». При создании одной из зависимостей behavior class выполняется behavior этого же класса. Внедрите зависимость лениво или сузьте matching rule:

    public function __construct(
    #[Autowire(lazy: true)] private readonly Wallet $wallet, // or #[AutowireServiceClosure(Wallet::class)], a service locator
    ) {}
  • «Class … was not found by locator». Класс внутри include paths расширяет код, который Composer не может найти, например сгенерированный базовый класс. Дайте Composer его найти, включите PARTIAL_REFLECTION или исключите зависимые классы через exclude_paths.

  • Обработчики исключений. Исключите через exclude_paths классы, которые должны загружаться, когда всё остальное уже сломалось (обработчики ошибок, ядро).

© 2026 Alexander Lisachenko