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

Ограничения и переход на 4.0

Что версия 4.0 не умеет перехватывать и как это обойти, а затем полное руководство по миграции с 3.x.

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

Эта страница состоит из двух частей. В первой перечислено, что версия 4.0 не перехватывает, почему и что делать вместо этого. Вторая — полное руководство по миграции с 3.x на 4.0, в том порядке, в котором его стоит применять.

Ограничения описаны как есть. Большинство из них идёт от самого PHP, и каждое проявляется предсказуемо: либо компилятор выбрасывает WeavingException на этапе компиляции, либо член класса пропускается.

Методы и функции, которые нельзя перехватить

Заголовок раздела «Методы и функции, которые нельзя перехватить»

Метод или функцию, объявленные как function &name(), перехватить нельзя. Call contexts (контексты вызова) и behaviors (поведения) возвращают значения, поэтому вызывающий код получил бы копию вместо ссылки. Компиляция такого метода завершается с WeavingException.

Исключите такие методы из широкого matching rule (правила выбора) с помощью !matchReturningByReference():

#[Around('execution(public App\Service\*->*(*)) && !matchReturningByReference()')]

В 3.x call context возвращал копию с notice. В 4.0 это ошибка, поэтому такие методы находятся ещё на этапе компиляции.

Метод, который класс импортирует из трейта и который помечен #[\Override], в этом классе перехватить нельзя. PHP копирует атрибут в приватный псевдоним, который вызывает прокси, а этот псевдоним ничего не переопределяет. Компиляция такого метода завершается с WeavingException.

Вариантов четыре:

  • Исключить методы трейтов из правила с помощью && !matchInherited().
  • Исключить только этот метод, например && !execution(public Foo->hello(*)).
  • Убрать #[\Override] из трейта.
  • Нацелиться на сам трейт, например execution(public HelloTrait->hello(*)). Тогда компилируется трейт, что работает с #[\Override], а behavior применяется в каждом классе, использующем этот трейт.

Методов трейтов, которые класс наследует от родительского класса, это не касается.

Для метода, содержащего yield, behavior выполняется в момент вызова метода, а proceed() возвращает объект Generator. Behavior не видит выдаваемых значений: они производятся позже, пока вызывающий код итерирует генератор.

getArguments() перечисляет аргументы по позициям. Вариативный параметр по ссылке (&...$values) передаётся в исходный метод по значению.

Прокси сохраняет атрибут. Фреймы самого фреймворка, которые передают аргументы массивом, их скрывают: __invoke() у call context, сгенерированный __initialization() и переписанный new.

Две встроенные функции между call context и исходным методом скрыть их не могут:

  • ReflectionMethod::invokeArgs() — для методов экземпляра и конструкторов
  • forward_static_call_array() — для статических методов

Их фреймы в Throwable::getTrace() по-прежнему содержат массив аргументов, который текстовая форма трассировки выводит как Array. Трекеры ошибок, собирающие аргументы фреймов, его видят. С zend.exception_ignore_args=On, значением по умолчанию для продакшена, аргументов нет ни в одном фрейме.

Прокси перехваченных функций генерируются с declare(strict_types=1), по одному файлу на пространство имён. Аргументы приводятся по режиму вызывающего файла ещё до входа в прокси.

Правила access(...) перехватывают чтение и запись свойств экземпляра через нативные хуки свойств PHP 8.4 на сгенерированном прокси: сгенерированные хуки направляют чтение и запись через call contexts ClassFieldAccess. Что это даёт, описано на странице о перехвате свойств. Следующие свойства намеренно пропускаются:

Свойство Почему
Свойства static В PHP нет хуков для статических свойств. Это ограничение движка.
Свойства readonly, включая public private(set) readonly PHP не разрешает хуки на readonly-свойствах.
Свойства, у которых уже есть хуки get или set Фреймворк не умеет совмещать свои хуки с вашими.
Унаследованные от родительских классов свойства final Не поддерживаются.
Унаследованные свойства private Не поддерживаются.

Поддерживаются свойства, объявленные в самом компилируемом классе, включая свойства, продвинутые через конструктор, а также унаследованные от родительских классов свойства public и protected.

Пропущенное свойство не вызывает ошибки. Если ваше правило его выбирает, свойство молча остаётся без перехвата: AdviceMatcher пропускает статические, readonly-свойства и свойства с хуками ещё до генерации кода прокси. Генератор свойств для страховки тоже отклоняет такое свойство с WeavingException.

Асимметричная видимость у не-readonly-свойств сохраняется. public protected(set) string $name сохраняет свои модификаторы в классе прокси.

Фреймворк строит перехват свойств на хуках свойств PHP 8.4, а его контейнер использует ленивые объекты PHP 8.4 для отложенных сервисов. У двух частей этой схемы есть ограничения.

Инициализацию ленивых объектов перехватить нельзя

Заголовок раздела «Инициализацию ленивых объектов перехватить нельзя»

В PHP 8.4 появились ReflectionClass::newLazyProxy() и ReflectionClass::newLazyGhost() для ленивой инициализации объектов. Container фреймворка использует нативные ленивые прокси для собственных отложенных сервисов и для behavior classes (классов поведений), зарегистрированных по имени класса. При получении такого сервиса выдаётся типизированный экземпляр newLazyProxy(), корректный для instanceof. Зарегистрированная фабрика выполняется только при первом реальном обращении к этому объекту.

Классы, которые PHP не может сделать ленивыми, создаются сразу: встроенные классы и их наследники, кроме наследников stdClass, абстрактные классы и перечисления.

Для момента, когда ленивый прокси материализует свой реальный экземпляр, call context не существует, поэтому саму инициализацию ленивого объекта перехватить нельзя.

Возможность PHP 8.4 Поддержка Примечания
Хуки свойств на новых свойствах Генерируются фреймворком Используются для перехвата access(...)
Свойства с уже существующими хуками Пропускаются Фреймворк не умеет совмещаться с пользовательскими хуками
Readonly-свойства Пропускаются Хуки на readonly-свойствах запрещены
Асимметричная видимость (не readonly) Сохраняется Модификаторы видимости копируются в прокси
Атрибут #[\Deprecated] Переносится Копируется в методы и классы прокси
Ленивые объекты (newLazyProxy) Не перехватываются Нет call context для ленивой инициализации

Заметки о PHP 8.5 основаны на аудите фреймворка на PHP 8.5.10 и PHP 8.6.0beta2.

  • Pipe-оператор |>. Работает внутри тел скомпилированных методов. Тела методов переносятся дословно в трейт тела <Class>OriginalTrait, поэтому любой синтаксис выражений PHP 8.5 в них сохраняется.
  • clone with. Такие выражения в скомпилированном коде работают как положено.
  • #[\NoDiscard]. Атрибут копируется в сгенерированный метод прокси, а call context возвращает значение перехваченного метода. Предупреждение движка «return value not used» продолжает срабатывать для скомпилированных методов.
  • Атрибуты на константах класса, включая #[\Deprecated]. Константы класса остаются в сгенерированном трейте вместе со своими атрибутами.
  • Замыкания и first-class callables как значения параметров по умолчанию. Они переживают компиляцию в сигнатурах методов прокси.
  • Статическая асимметричная видимость. Свойства static с асимметричной видимостью (public static private(set)) работают в скомпилированных классах. Правила access(...) на них никогда не нацеливаются.
  • Разрешение self и parent через рефлексию. В PHP 8.5 ReflectionNamedType::getName() разрешает типы возврата self и parent в конкретные имена классов. Генераторы прокси там, где это возможно, читают исходный узел типа из AST, поэтому ключевые слова self и parent в сгенерированных прокси сохраняются.

Выражение new в константном выражении вычисляет движок. Сюда относятся значение по умолчанию параметра или продвинутого параметра конструктора, инициализатор статической переменной и аргумент атрибута. Компилятор оставляет эти выражения как есть, поэтому код работает, но behavior initialization(...) для созданных ими объектов не выполняется. Перехватываются только выражения new в исполняемом коде.

Статические свойства никогда не перехватываются

Заголовок раздела «Статические свойства никогда не перехватываются»

Статические свойства, включая свойства static с асимметричной видимостью из PHP 8.5, нельзя перехватить правилами access(...). Хуков свойств для статических свойств в PHP нет, поэтому у фреймворка нет механизма их перехвата, и AdviceMatcher исключает их из перехвата свойств. Это ограничение движка PHP, а не ошибка.

Возможность PHP 8.5 Поддержка Примечания
Pipe-оператор |> в телах методов Работает Тела переносятся дословно в сгенерированный трейт
clone with Работает
#[\NoDiscard] Переносится Копируется в прокси; call context возвращает значение
Атрибуты на константах класса (включая #[\Deprecated]) Сохраняются Константы остаются в сгенерированном трейте
Замыкания и first-class callables как значения параметров по умолчанию Работает
Статическая асимметричная видимость (без перехвата) Сохраняется Статические свойства никогда не перехватываются через access()
Разрешение self/parent через рефлексию Учтено При генерации прокси используются исходные узлы типов из AST
new в инициализаторах Не перехватывается Вычисляется движком; behaviors initialization(...) для него не выполняются
Перехват статических свойств через access() Никогда Нет хуков для статических свойств (ограничение движка PHP)

Область компиляции и ограничения matching rules

Заголовок раздела «Область компиляции и ограничения matching rules»

Компилируются только классы, загруженные после инициализации ядра (kernel). Класс, загруженный раньше, работает без своих behaviors. Инициализируйте ядро как можно раньше в фронт-контроллере. Мосты (bridges) к фреймворкам должны загружаться первыми; как это делает каждый мост, описано на странице Интеграции.

Список аргументов в matching rule всегда (*). Правило выбирает методы по классу, имени, модификаторам, типу возврата и атрибутам, но никогда по значениям аргументов или типам параметров. Чтобы реагировать на конкретные аргументы, выберите метод и проверьте $invocation->getArguments() внутри behavior. Полный синтаксис описан на странице Поведения и правила выбора.

Затраты во время выполнения, о которых стоит знать

Заголовок раздела «Затраты во время выполнения, о которых стоит знать»

Эти цифры взяты из собственного бенчмарка фреймворка в docs/performance.md: небольшое приложение интернет-магазина примерно из 250 файлов, 94 компилируемых класса и 6 behavior classes, PHP 8.5.12 с выключенным JIT. В файле объяснено, как они измерялись и как их воспроизвести.

Пока зарегистрировано правило initialization, каждый new в сгенерированных файлах проходит через трансформер. Класс без behaviors на инициализацию (и с публичным конструктором) по-прежнему создаётся нативным new, что стоит примерно на 130 нс больше, чем обычный new. Класс с behaviors на инициализацию проходит через полный call context. Предпочитайте правила на методы там, где они справляются с задачей.

С 'debug' => true сгенерированные классы отдаются через stream filter, поэтому точки останова Xdebug и магические константы указывают на ваши исходные файлы, а изменённые файлы перекомпилируются автоматически. В бенчмарке горячие запросы в режиме отладки выполняются более чем вдвое дольше, чем в продакшен-режиме. В продакшене используйте 'debug' => false; см. страницу Продакшен и производительность.

Версия 4.0 заменяет компилятор на основе наследования компилятором на основе трейтов, генерирует behaviors как first-class callables и перестраивает кеши под PHP 8.4. Большинству приложений достаточно чек-листа ниже. Разделы после него описывают каждое несовместимое изменение. Имена API в них сохраняют классические термины; таблица терминов сопоставляет их со словами, которые используются здесь. Полный список изменений — в CHANGELOG.

  1. Перейдите на PHP 8.4 или новее и обновите зависимости (см. «Требования и зависимости» ниже).

  2. Сделайте каждый метод behavior в ваших behavior classes public (см. «Behavior classes» ниже).

  3. Регистрируйте behavior classes через add() или addLazyService() вместо registerAspect().

  4. Замените шаблоны ? в matching rules на * и перепишите правила dynamic(...).

  5. Удалите каталог кеша, затем прогрейте его заново. Аргумент — это файл, который инициализирует ваше ядро:

    Окно терминала
    vendor/bin/aspect cache:warmup:aop public/index.php
  6. Если вы используете мост Doctrine, переведите обнаружение сущностей на WovenEntityClassLocator.

  • PHP 8.4+ с ext-tokenizer.
  • Обновите зависимости через Composer. Нужные версии указаны в composer.json.
  • psr/container — новая зависимость, а nikic/php-parser устанавливается через goaop/parser-reflection.
  • laminas/laminas-code больше не используется. Прокси генерирует внутренний пакет Go\Proxy\Generator. Код, который расширял генераторы фреймворка или полагался на классы генераторов laminas, приходившие вместе с фреймворком, нужно обновить.
  • Для bin/aspect нужен symfony/console.

Все форматы кеша изменились, и ни один файл кеша из 3.x повторно не используется.

  • Структура прокси. Подкаталога _proxies больше нет. Прокси хранится по относительному пути своего исходного файла внутри каталога кеша, а сгенерированный исходник (исходное тело класса в виде трейта <Class>OriginalTrait) — рядом с ним.
  • Карта классов. _include.cache сопоставляет каждый скомпилированный класс с его закешированным файлом и передаётся Composer при загрузке. Кроме того, она сопоставляет каждый известный исходный файл с его закешированным файлом (или null, если файл не трансформирован) для подключений, перехватываемых через INTERCEPT_INCLUDES. Каталог кеша без неё считается устаревшим.
  • Кеш behavior classes. Сериализованные блобы {cacheDir}/_aspect/sha1(FQCN) заменены обычными PHP-файлами рядом со сгенерированными исходниками: {appDir}/src/Aspect/LoggingAspect.php кешируется как {cacheDir}/src/Aspect/LoggingAspect.cache.php. Перехватчики больше не сериализуются: AbstractInterceptor::__serialize(), __unserialize(), serializeAdvice() и unserializeAdvice() удалены.

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

Features::PREBUILT_CACHE теперь полностью доверяет кешу. Проверки каталога и доступности на запись, сравнения filemtime, проверки отслеживаемых ресурсов и проверки свежести кешей behavior classes — всё это пропускается. Пересборка кеша при деплое — ответственность того, кто деплоит.

Опция cacheFileMode проверяется. Это должно быть целое число от 0600 до 0777, дающее владельцу права на чтение и запись. Каталоги получают права на поиск, соответствующие битам чтения этого режима.

Сгенерированные прокси вызывают behaviors как first-class callables на экземпляре behavior class. Поэтому метод с #[Before], #[After], #[Around] или #[AfterThrowing] должен быть public. Для защищённых или приватных методов behavior загрузчик выбрасывает AspectException. Методы, у которых есть только #[Pointcut], могут иметь любую видимость.

3.x
#[Before('execution(public Example->*(*))')]
protected function beforeMethod(MethodInvocation $invocation): void {}
// 4.0
#[Before('execution(public Example->*(*))')]
public function beforeMethod(MethodInvocation $invocation): void {}

Метод behavior class несёт не больше одного из атрибутов #[Before], #[After], #[Around] и #[AfterThrowing]. Второй такой атрибут приводит к AspectException. Разделите такой метод на отдельные методы, по одному на behavior. #[Pointcut] по-прежнему можно сочетать с атрибутом behavior на одном методе, а атрибуты, не принадлежащие фреймворку, игнорируются.

AspectContainer::registerAspect() удалён. Behavior classes — это обычные сервисы контейнера.

Раньше, в 3.x:

app/ApplicationAspectKernel.php
// 3.x
protected function configureAop(AspectContainer $container)
{
$container->registerAspect(new MonitorAspect());
}

Теперь, в 4.0:

app/ApplicationAspectKernel.php
// 4.0
protected function configureAop(AspectContainer $container): void
{
// Deferred (recommended): constructed when one of its behaviors runs for the first time
$container->addLazyService(MonitorAspect::class, static fn() => new MonitorAspect());
// Eager alternative
// $container->add(MonitorAspect::class, new MonitorAspect());
}

addLazyService() сохраняет фабрику и создаёт сервис при первом получении. Код, который ожидал, что экземпляр ленивого прокси существует уже при загрузке, должен вызвать getService(). Фабрика, возвращающая объект неправильного типа, теперь падает при первом использовании, а не при регистрации.

AspectContainer::addResource() входит в интерфейс. onRegistration() позволяет реагировать на отложенную регистрацию сервисов, реализующих интерфейс.

AspectContainer расширяет Psr\Container\ContainerInterface, поэтому контейнер можно передать в любой код, который ожидает контейнер PSR-11.

  • AspectContainer::getValue() переименован в get().
  • has() приходит из интерфейса PSR, с той же сигнатурой.
  • Собственный containerClass реализует get() вместо getValue(), а также setDelegate(), который подключает контейнер вашего приложения. См. страницу Конфигурация и CLI.
4.0
// before
$pointcut = $container->getValue('my.pointcut');
$pointcut = $container->get('my.pointcut');

Неизвестный id приводит к ServiceNotFoundException, который реализует Psr\Container\NotFoundExceptionInterface. getService() выбрасывает Go\Aop\Exception\ContainerException, если запись не является экземпляром запрошенного класса. Это исключение — InvalidConfigurationException, реализующее Psr\Container\ContainerExceptionInterface.

Переименование касается только контейнера. FieldAccess::getValue() у call contexts свойств не изменился.

  • Маркерные интерфейсы AdviceBefore, AdviceAfter и AdviceAround удалены. Advice требует getType(): AdviceTypeEnum с вариантами Before, After, AfterThrowing, Around и Introduction.
  • Конструкторы invocation-классов (DynamicTraitAliasMethodInvocation, StaticTraitAliasMethodInvocation, ReflectionFunctionInvocation) требуют ненулевой Closure $closureToCall.
  • DeclareError удалён: атрибут, DeclareErrorInterceptor и PointcutBuilder::declareError(). Вместо этого выдавайте предупреждения или выбрасывайте исключения из behavior #[Before] или #[Around].

Методы, возвращающие по ссылке, отклоняются

Заголовок раздела «Методы, возвращающие по ссылке, отклоняются»

Компиляция метода или функции, объявленных как function &name(), завершается с WeavingException, потому что call context вернул бы копию вместо ссылки. 3.x возвращала копию с notice. Добавьте && !matchReturningByReference() к правилам, которые выбирают такие методы.

? в шаблонах имён и типов больше не означает один любой символ, потому что конфликтовал с nullable-типами. В шаблонах типа возврата ведущий ? — маркер nullable: ?Foo равно Foo|null. Замените шаблоны ? на *.

Правило dynamic(...) удалено вместе с MagicMethodDynamicPointcut, DynamicInvocationMatcherInterceptor, Pointcut::KIND_DYNAMIC и параметрами $instanceOrScope и $arguments метода Pointcut::matches(). Перехватывайте сам магический метод и читайте вызванное имя из аргументов.

Раньше, в 3.x:

3.x
#[Around('dynamic(public Foo->save*(*))')]

Теперь, в 4.0:

4.0
#[Around('execution(public Foo->__call(*))')]
public function aroundMagicCall(MethodInvocation $invocation): mixed
{
[$methodName, $arguments] = $invocation->getArguments();
// ...
return $invocation->proceed();
}
  • Приоритет модификаторов. Все модификаторы, перечисленные через пробел, должны присутствовать, а | связывает сильнее. final public|protected означает final И (public ИЛИ protected). В 3.x это правило также выбирало каждый не-final публичный метод.
  • Foo+ включает Foo. Теперь он выбирает и сам класс или интерфейс Foo, и классы, использующие трейт Foo. Добавьте && !within(Foo), чтобы исключить сам тип.
  • Правила по атрибутам выбирают и подклассы. @execution(Attr) и другие правила по атрибутам выбирают и атрибуты, расширяющие Attr.
  • * выбирает и пустую строку. В шаблонах имён и типов возврата * означает любые символы одной части имени, в том числе ни одного. В 3.x требовался хотя бы один символ: Sensor* пропускал сам класс Sensor, а set* пропускал метод с именем set(). Теперь такие правила выбирают и их. При необходимости исключите их через && !execution(public Foo->set(*)) или && !within(Foo).
  • Альтернативы | остаются внутри своей части имени. Ns\A|B выбирает Ns\A и Ns\B. В 3.x это означало Ns\A или глобальный класс B. Шаблон, который перечислял классы из разных пространств имён (Foo\A|Bar\B), нужно записать двумя правилами: execution(public Foo\A->*(*)) || execution(public Bar\B->*(*)).
  • ModifierPointcut — final и неизменяемый. Маски передаются аргументами конструктора, а andMatch(), orMatch() и notMatch() возвращают новый экземпляр.

Исходное тело класса превращается в трейт <Class>OriginalTrait. Класс прокси сохраняет исходное имя, родителя и интерфейсы и использует этот трейт с приватными псевдонимами <method>OriginalAlias. В 3.x прокси наследовал переименованный родительский класс <Class>__AopProxied. Это затрагивает код, который полагался на этот слой наследования:

  • У прокси больше нет переименованного родительского класса. get_parent_class(), parent:: внутри класса и проверки instanceof видят исходного родителя.
  • AspectContainer::AOP_PROXIED_SUFFIX удалён. Используйте ORIGINAL_TRAIT_SUFFIX ('OriginalTrait') или ORIGINAL_TRAIT_FILE_SUFFIX ('OriginalTrait.php').
  • AbstractMethodInvocation::TRAIT_ALIAS_PREFIX заменён на TRAIT_ALIAS_SUFFIX ('OriginalAlias').
  • Хуки InitializationAware и StaticInitializationAware называются __initialization() и __staticInitialization().
  • self:: в сгенерированном коде разрешается в класс прокси, поэтому SelfValueTransformer и SelfValueVisitor удалены.
  • Go\Aop\Features — теперь final-класс, а не интерфейс. Константы не изменились, но реализовать его больше нельзя. Features::ALL объединяет все флаги, а AspectKernel::hasFeature() выбрасывает исключение на неизвестном флаге.
  • Features::PARAMETER_WIDENING удалён. Если вы передавали этот флаг, уберите его из параметров ядра.

Эти публичные классы, методы и константы не использовались внутри фреймворка и удалены:

  • Атрибут #[Aspect] (Go\Lang\Attribute\Aspect). Фреймворк его никогда не читал: behavior classes определяются по реализации Go\Aop\Aspect. Уберите этот атрибут из своих behavior classes.
  • Pointcut::KIND_TRAIT. Pointcut::KIND_ALL равен 119 вместо 127.
  • Go\Proxy\Part\InterceptedConstructorGenerator и Go\Proxy\Part\FunctionParameterList.
  • InterceptedMethodGenerator::getBody() и setBody(), CachePathManager::setCacheDir() и AopComposerLoader::wasInitialized(). AopComposerLoader::init() возвращает тот же флаг.
  • Запись контейнера 'kernel.options'. Используйте AspectKernel::getOptions().

Переименованные перечисления и константы

Заголовок раздела «Переименованные перечисления и константы»
3.x / ранняя разработка 4.0 4.0
TransformerResultEnum::RESULT_TRANSFORMED TransformerResult::Transformed
TransformerResultEnum::RESULT_ABSTAIN TransformerResult::Abstain
TransformerResultEnum::RESULT_ABORTED TransformerResult::Aborted
FieldAccessType::READ / WRITE FieldAccessType::Read / Write
AspectContainer::AOP_PROXIED_SUFFIX AspectContainer::ORIGINAL_TRAIT_SUFFIX
AspectContainer::getValue() AspectContainer::get() (PSR-11)

Перечисления Go\Proxy\Generator (Visibility, PropertyModifier, ClassModifier) тоже используют варианты в PascalCase. Собственные трансформеры исходников возвращают варианты TransformerResult, а behaviors, сравнивающие getAccessType(), используют новые имена вариантов:

if ($access->getAccessType() === FieldAccessType::WRITE) {
if ($access->getAccessType() === FieldAccessType::Write) {
  • AspectKernel::registerTransformers(), возвращавший экземпляры трансформеров, заменён на registerTransformerServices(AspectContainer $container), который регистрирует отложенные сервисы контейнера. Переопределите его, чтобы заменить, убрать, переупорядочить или расширить встроенные трансформеры. Чтобы добавить трансформер в конец, вызовите $container->addLazyService(MyTransformer::class, ...) из configureAop().
  • CachingTransformer удалён: решение о кеше принимается в SourceTransformingLoader. SourceTransformingLoader::addTransformer() удалён, а transformCode() возвращает общий TransformerResult.
  • StreamMetaData::$source доступен только для чтения: он заново собирается из $tokenStream при каждом чтении. Собственные трансформеры правят токены в $tokenStream или заменяют их через setTokenStreamFromRawTokens().
  • ConstructorExecutionTransformer, FilterInjectorTransformer и MagicConstantTransformer больше не являются SourceTransformer. Это правила NodeRewriter, которые применяет один обход синтаксического дерева SyntaxTreeRewriter. Этот обход — сервис фреймворка: он открывает цепочку перед WeavingTransformer, даже если registerTransformerServices() переопределён.
  • Собственные SourceTransformer регистрируются как прежде. Чтобы переписывать отдельные узлы, регистрируйте сервис NodeRewriter вместо трансформера, который сам обходит дерево. О расширении конвейера трансформаций — на странице Конфигурация и CLI.

Классы, которые никогда не предназначались для наследования, теперь final:

  • Go\Core\Container, Go\Core\AttributeAspectLoaderExtension
  • Go\Aop\Framework\StaticInitializationJoinpoint
  • Go\Instrument\ClassLoading\AopComposerLoader, SourceTransformingLoader, Go\Instrument\PathResolver
  • трансформеры WeavingTransformer, FilterInjectorTransformer, MagicConstantTransformer и StreamMetaData
  • генераторы прокси EnumProxyGenerator, TraitProxyGenerator и FunctionProxyGenerator
  • атрибуты #[Before], #[After], #[Around], #[AfterThrowing], #[Pointcut] и #[DeclareParents]

Go\Lang\Attribute\AbstractInterceptor — abstract. Классы, которые относятся только к внутреннему механизму фреймворка, помечены @internal и не покрываются обещаниями обратной совместимости: AdviceMatcher, AspectLoader, CachedAspectLoader, CachePathManager, CacheWarmer, Enumerator, InterceptorInjector, The и NativeLazyProxy.

Замените наследников этих классов композицией или собственным контейнером либо трансформером, зарегистрированным в configureAop() или registerTransformerServices().

Каждое исключение, которое выбрасывает фреймворк, реализует Go\Aop\Exception\ExceptionInterface, так что один catch обрабатывает любой его сбой. В нескольких местах тип исключения изменился:

Ситуация 3.x 4.0
Неверные параметры ядра, регистрации в контейнере, консольный ввод RuntimeException, InvalidArgumentException, UnexpectedValueException InvalidConfigurationException (это InvalidArgumentException)
Неверное matching rule UnexpectedValueException, InvalidArgumentException PointcutSyntaxException (это AspectException)
Неизвестный id в контейнере OutOfBoundsException ServiceNotFoundException (это OutOfBoundsException и NotFoundExceptionInterface из PSR-11)
Запись контейнера неправильного типа в getService() InvalidArgumentException ContainerException (это InvalidConfigurationException и ContainerExceptionInterface из PSR-11)
Компиляция, генерация прокси, запись кеша RuntimeException, LogicException, InvalidArgumentException WeavingException (это RuntimeException)
Behavior, который нельзя закешировать Go\Core\Cache\NotCompilableException Go\Aop\Exception\NotCompilableException
Неверный behavior class, ошибки call context во время выполнения Go\Aop\AspectException Go\Aop\Exception\AspectException, Go\Aop\Exception\InvocationException

Там, где вы перехватывали перечисленные выше типы SPL, перехватывайте ExceptionInterface или новые типы.

Мост больше не переписывает метаданные сущностей. Обходной путь с mapped superclass из 3.x был нужен только движку на основе наследования, а Doctrine правильно отображает скомпилированную сущность как есть. Вместо этого настройте две вещи (Doctrine ORM 3.6+):

use Doctrine\ORM\Events;
use Doctrine\ORM\Mapping\Driver\AttributeDriver;
use Go\Bridge\Doctrine\MetadataLoadInterceptor;
use Go\Bridge\Doctrine\WovenEntityClassLocator;
// Discover entities through the autoloader, which serves the generated classes
$configuration->setMetadataDriverImpl(
new AttributeDriver(WovenEntityClassLocator::createFromDirectories([__DIR__ . '/src/Entity'])),
);
// Intercepted properties become hooked properties, which Doctrine supports with native lazy objects
$configuration->enableNativeLazyObjects(true);
// Optional: reports misconfiguration early; a plain listener, no longer an EventSubscriber
$eventManager->addEventListener(Events::loadClassMetadata, new MetadataLoadInterceptor());

Команды объявляют свои имена через #[AsCommand] и загружаются лениво из bin/aspect. Каждая команда возвращает Command::SUCCESS или Command::FAILURE.

  • В 3.x debug:weaving возвращала количество ошибок как есть. Если скрипт полагался на это число, проверяйте вместо него код выхода.
  • cache:warmup:aop завершается с ошибкой, если файл не компилируется, так что скрипт деплоя, который игнорировал ошибки прогрева, теперь на этом остановится. Добавьте --fail-fast, чтобы остановиться на первой ошибке:
Окно терминала
vendor/bin/aspect cache:warmup:aop public/index.php --fail-fast

© 2026 Alexander Lisachenko