Ограничения и переход на 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]
Заголовок раздела «Методы трейтов с #[\Override]»Метод, который класс импортирует из трейта и который помечен #[\Override], в этом классе перехватить нельзя. PHP копирует атрибут в приватный псевдоним, который вызывает прокси, а этот псевдоним ничего не переопределяет. Компиляция такого метода завершается с WeavingException.
Вариантов четыре:
- Исключить методы трейтов из правила с помощью
&& !matchInherited(). - Исключить только этот метод, например
&& !execution(public Foo->hello(*)). - Убрать
#[\Override]из трейта. - Нацелиться на сам трейт, например
execution(public HelloTrait->hello(*)). Тогда компилируется трейт, что работает с#[\Override], а behavior применяется в каждом классе, использующем этот трейт.
Методов трейтов, которые класс наследует от родительского класса, это не касается.
Генераторы
Заголовок раздела «Генераторы»Для метода, содержащего yield, behavior выполняется в момент вызова метода, а proceed() возвращает объект Generator. Behavior не видит выдаваемых значений: они производятся позже, пока вызывающий код итерирует генератор.
Вариативные параметры по ссылке
Заголовок раздела «Вариативные параметры по ссылке»getArguments() перечисляет аргументы по позициям. Вариативный параметр по ссылке (&...$values) передаётся в исходный метод по значению.
#[\SensitiveParameter] в трассировках стека
Заголовок раздела «#[\SensitiveParameter] в трассировках стека»Прокси сохраняет атрибут. Фреймы самого фреймворка, которые передают аргументы массивом, их скрывают: __invoke() у call context, сгенерированный __initialization() и переписанный new.
Две встроенные функции между call context и исходным методом скрыть их не могут:
ReflectionMethod::invokeArgs()— для методов экземпляра и конструкторовforward_static_call_array()— для статических методов
Их фреймы в Throwable::getTrace() по-прежнему содержат массив аргументов, который текстовая форма трассировки выводит как Array. Трекеры ошибок, собирающие аргументы фреймов, его видят. С zend.exception_ignore_args=On, значением по умолчанию для продакшена, аргументов нет ни в одном фрейме.
strict_types прокси функций
Заголовок раздела «strict_types прокси функций»Прокси перехваченных функций генерируются с 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, а его контейнер использует ленивые объекты PHP 8.4 для отложенных сервисов. У двух частей этой схемы есть ограничения.
Инициализацию ленивых объектов перехватить нельзя
Заголовок раздела «Инициализацию ленивых объектов перехватить нельзя»В PHP 8.4 появились ReflectionClass::newLazyProxy() и ReflectionClass::newLazyGhost() для ленивой инициализации объектов. Container фреймворка использует нативные ленивые прокси для собственных отложенных сервисов и для behavior classes (классов поведений), зарегистрированных по имени класса. При получении такого сервиса выдаётся типизированный экземпляр newLazyProxy(), корректный для instanceof. Зарегистрированная фабрика выполняется только при первом реальном обращении к этому объекту.
Классы, которые PHP не может сделать ленивыми, создаются сразу: встроенные классы и их наследники, кроме наследников stdClass, абстрактные классы и перечисления.
Для момента, когда ленивый прокси материализует свой реальный экземпляр, call context не существует, поэтому саму инициализацию ленивого объекта перехватить нельзя.
Сводка по PHP 8.4
Заголовок раздела «Сводка по PHP 8.4»| Возможность PHP 8.4 | Поддержка | Примечания |
|---|---|---|
| Хуки свойств на новых свойствах | Генерируются фреймворком | Используются для перехвата access(...) |
| Свойства с уже существующими хуками | Пропускаются | Фреймворк не умеет совмещаться с пользовательскими хуками |
| Readonly-свойства | Пропускаются | Хуки на readonly-свойствах запрещены |
| Асимметричная видимость (не readonly) | Сохраняется | Модификаторы видимости копируются в прокси |
Атрибут #[\Deprecated] |
Переносится | Копируется в методы и классы прокси |
Ленивые объекты (newLazyProxy) |
Не перехватываются | Нет call context для ленивой инициализации |
Заметки о PHP 8.5
Заголовок раздела «Заметки о PHP 8.5»Заметки о PHP 8.5 основаны на аудите фреймворка на PHP 8.5.10 и PHP 8.6.0beta2.
Что работает на PHP 8.5
Заголовок раздела «Что работает на PHP 8.5»- 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.5ReflectionNamedType::getName()разрешает типы возвратаselfиparentв конкретные имена классов. Генераторы прокси там, где это возможно, читают исходный узел типа из AST, поэтому ключевые словаselfиparentв сгенерированных прокси сохраняются.
new в инициализаторах не перехватывается
Заголовок раздела «new в инициализаторах не перехватывается»Выражение new в константном выражении вычисляет движок. Сюда относятся значение по умолчанию параметра или продвинутого параметра конструктора, инициализатор статической переменной и аргумент атрибута. Компилятор оставляет эти выражения как есть, поэтому код работает, но behavior initialization(...) для созданных ими объектов не выполняется. Перехватываются только выражения new в исполняемом коде.
Статические свойства никогда не перехватываются
Заголовок раздела «Статические свойства никогда не перехватываются»Статические свойства, включая свойства static с асимметричной видимостью из PHP 8.5, нельзя перехватить правилами access(...). Хуков свойств для статических свойств в PHP нет, поэтому у фреймворка нет механизма их перехвата, и AdviceMatcher исключает их из перехвата свойств. Это ограничение движка PHP, а не ошибка.
Сводка по PHP 8.5
Заголовок раздела «Сводка по PHP 8.5»| Возможность 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
Заголовок раздела «Правила initialization() затрагивают каждый new»Пока зарегистрировано правило initialization, каждый new в сгенерированных файлах проходит через трансформер. Класс без behaviors на инициализацию (и с публичным конструктором) по-прежнему создаётся нативным new, что стоит примерно на 130 нс больше, чем обычный new. Класс с behaviors на инициализацию проходит через полный call context. Предпочитайте правила на методы там, где они справляются с задачей.
Режим отладки — для разработки
Заголовок раздела «Режим отладки — для разработки»С 'debug' => true сгенерированные классы отдаются через stream filter, поэтому точки останова Xdebug и магические константы указывают на ваши исходные файлы, а изменённые файлы перекомпилируются автоматически. В бенчмарке горячие запросы в режиме отладки выполняются более чем вдвое дольше, чем в продакшен-режиме. В продакшене используйте 'debug' => false; см. страницу Продакшен и производительность.
Переход с 3.x на 4.0
Заголовок раздела «Переход с 3.x на 4.0»Версия 4.0 заменяет компилятор на основе наследования компилятором на основе трейтов, генерирует behaviors как first-class callables и перестраивает кеши под PHP 8.4. Большинству приложений достаточно чек-листа ниже. Разделы после него описывают каждое несовместимое изменение. Имена API в них сохраняют классические термины; таблица терминов сопоставляет их со словами, которые используются здесь. Полный список изменений — в CHANGELOG.
Краткий чек-лист
Заголовок раздела «Краткий чек-лист»-
Перейдите на PHP 8.4 или новее и обновите зависимости (см. «Требования и зависимости» ниже).
-
Сделайте каждый метод behavior в ваших behavior classes
public(см. «Behavior classes» ниже). -
Регистрируйте behavior classes через
add()илиaddLazyService()вместоregisterAspect(). -
Замените шаблоны
?в matching rules на*и перепишите правилаdynamic(...). -
Удалите каталог кеша, затем прогрейте его заново. Аргумент — это файл, который инициализирует ваше ядро:
Окно терминала vendor/bin/aspect cache:warmup:aop public/index.php -
Если вы используете мост 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, дающее владельцу права на чтение и запись. Каталоги получают права на поиск, соответствующие битам чтения этого режима.
Behavior classes
Заголовок раздела «Behavior classes»Методы behavior должны быть публичными
Заголовок раздела «Методы behavior должны быть публичными»Сгенерированные прокси вызывают behaviors как first-class callables на экземпляре behavior class. Поэтому метод с #[Before], #[After], #[Around] или #[AfterThrowing] должен быть public. Для защищённых или приватных методов behavior загрузчик выбрасывает AspectException. Методы, у которых есть только #[Pointcut], могут иметь любую видимость.
#[Before('execution(public Example->*(*))')]protected function beforeMethod(MethodInvocation $invocation): void {}
// 4.0#[Before('execution(public Example->*(*))')]public function beforeMethod(MethodInvocation $invocation): void {}Один атрибут behavior на метод
Заголовок раздела «Один атрибут behavior на метод»Метод behavior class несёт не больше одного из атрибутов #[Before], #[After], #[Around] и #[AfterThrowing]. Второй такой атрибут приводит к AspectException. Разделите такой метод на отдельные методы, по одному на behavior. #[Pointcut] по-прежнему можно сочетать с атрибутом behavior на одном методе, а атрибуты, не принадлежащие фреймворку, игнорируются.
Регистрация behavior classes
Заголовок раздела «Регистрация behavior classes»AspectContainer::registerAspect() удалён. Behavior classes — это обычные сервисы контейнера.
Раньше, в 3.x:
// 3.xprotected function configureAop(AspectContainer $container){ $container->registerAspect(new MonitorAspect());}Теперь, в 4.0:
// 4.0protected 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() позволяет реагировать на отложенную регистрацию сервисов, реализующих интерфейс.
Контейнер PSR-11
Заголовок раздела «Контейнер PSR-11»AspectContainer расширяет Psr\Container\ContainerInterface, поэтому контейнер можно передать в любой код, который ожидает контейнер PSR-11.
AspectContainer::getValue()переименован вget().has()приходит из интерфейса PSR, с той же сигнатурой.- Собственный
containerClassреализуетget()вместоgetValue(), а такжеsetDelegate(), который подключает контейнер вашего приложения. См. страницу Конфигурация и CLI.
// 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 свойств не изменился.
Advice и API перехватчиков
Заголовок раздела «Advice и API перехватчиков»- Маркерные интерфейсы
AdviceBefore,AdviceAfterиAdviceAroundудалены.AdviceтребуетgetType(): AdviceTypeEnumс вариантамиBefore,After,AfterThrowing,AroundиIntroduction. - Конструкторы invocation-классов (
DynamicTraitAliasMethodInvocation,StaticTraitAliasMethodInvocation,ReflectionFunctionInvocation) требуют ненулевойClosure $closureToCall. DeclareErrorудалён: атрибут,DeclareErrorInterceptorиPointcutBuilder::declareError(). Вместо этого выдавайте предупреждения или выбрасывайте исключения из behavior#[Before]или#[Around].
Matching rules
Заголовок раздела «Matching rules»Методы, возвращающие по ссылке, отклоняются
Заголовок раздела «Методы, возвращающие по ссылке, отклоняются»Компиляция метода или функции, объявленных как function &name(), завершается с WeavingException, потому что call context вернул бы копию вместо ссылки. 3.x возвращала копию с notice. Добавьте && !matchReturningByReference() к правилам, которые выбирают такие методы.
Шаблон ? удалён
Заголовок раздела «Шаблон ? удалён»? в шаблонах имён и типов больше не означает один любой символ, потому что конфликтовал с nullable-типами. В шаблонах типа возврата ведущий ? — маркер nullable: ?Foo равно Foo|null. Замените шаблоны ? на *.
dynamic(...) удалён
Заголовок раздела «dynamic(...) удалён»Правило dynamic(...) удалено вместе с MagicMethodDynamicPointcut, DynamicInvocationMatcherInterceptor, Pointcut::KIND_DYNAMIC и параметрами $instanceOrScope и $arguments метода Pointcut::matches(). Перехватывайте сам магический метод и читайте вызванное имя из аргументов.
Раньше, в 3.x:
#[Around('dynamic(public Foo->save*(*))')]Теперь, в 4.0:
#[Around('execution(public Foo->__call(*))')]public function aroundMagicCall(MethodInvocation $invocation): mixed{ [$methodName, $arguments] = $invocation->getArguments(); // ... return $invocation->proceed();}Изменившиеся matching rules
Заголовок раздела «Изменившиеся matching rules»- Приоритет модификаторов. Все модификаторы, перечисленные через пробел, должны присутствовать, а
|связывает сильнее.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удалён. Если вы передавали этот флаг, уберите его из параметров ядра.
Удалённый неиспользуемый API
Заголовок раздела «Удалённый неиспользуемый API»Эти публичные классы, методы и константы не использовались внутри фреймворка и удалены:
- Атрибут
#[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- и внутренние классы
Заголовок раздела «Final- и внутренние классы»Классы, которые никогда не предназначались для наследования, теперь final:
Go\Core\Container,Go\Core\AttributeAspectLoaderExtensionGo\Aop\Framework\StaticInitializationJoinpointGo\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 или новые типы.
Мост Doctrine
Заголовок раздела «Мост Doctrine»Мост больше не переписывает метаданные сущностей. Обходной путь с 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
