Поведения и правила выбора
Полный справочник по поведениям — динамическим промежуточным слоям, которые фреймворк выполняет вокруг вашего кода, — и по правилам выбора, которые определяют, где они применяются.
Перевод с английского. Эталоном считается английская версия страницы. Читать оригинал
На этой странице собрано всё, что вы пишете при работе с фреймворком: behavior classes (классы поведений), behaviors (поведения) в них, которые выполняются вокруг вашего кода как динамический middleware (промежуточный слой), call context (контекст вызова), который получает каждый behavior, и matching rules (правила выбора), определяющие, где он выполняется. Если ядро ещё не настроено, начните со страницы Начало работы. Полные разборы от задачи до работающего кода — на страницах Кеширование результатов и Логирование вызовов.
Термины на этой странице
Заголовок раздела «Термины на этой странице»API фреймворка сохраняет классические названия, поэтому вы встретите их в коде, в именах классов и в сообщениях об ошибках. Эта документация использует повседневные слова и один раз называет соответствующий термин API:
| В этой документации | В API | Что это |
|---|---|---|
| Behavior class (класс поведений) | Aspect (аспект) | Класс, который реализует Go\Aop\Aspect и объединяет связанные behaviors |
| Behavior (поведение), middleware (промежуточный слой) | Advice (совет) | Публичный метод behavior class с одним атрибутом из Go\Lang\Attribute: #[Before], #[After], #[AfterThrowing] или #[Around] |
| Matching rule (правило выбора) | Pointcut (срез) | Выражение в этом атрибуте, которое выбирает, где выполняется behavior |
| Call context (контекст вызова) | Joinpoint (точка соединения) | Перехваченный момент (вызов метода, обращение к свойству, создание объекта), который передаётся в behavior в виде объекта |
| Compile step (этап компиляции) | Weaving (вплетение) | Превращение ваших классов в файлы, которые загружает PHP, с подключёнными behaviors |
| Class extension (расширение класса) | Introduction (внедрение) | Интерфейс и трейт, добавленные к существующим классам |
Behavior classes
Заголовок раздела «Behavior classes»namespace App\Aspect;
use Go\Aop\Aspect;use Go\Aop\Intercept\MethodInvocation;use Go\Lang\Attribute\AfterThrowing;use Go\Lang\Attribute\Around;use Psr\Log\LoggerInterface;
class ServiceAspect 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->debug($invocation . ' took ' . (hrtime(true) - $start) . ' ns'); } }
#[AfterThrowing('execution(public App\Service\*->*(*))')] public function logFailure(MethodInvocation $invocation, \Throwable $exception): void { $this->logger->error($invocation . ' failed: ' . $exception->getMessage()); }}Behavior class — это обычный PHP-класс, реализующий Go\Aop\Aspect. В нём живёт логика вроде логирования, кеширования, проверок безопасности или транзакций, которую иначе пришлось бы копировать во множество классов. Каждый его behavior выполняется как middleware вокруг кода, выбранного его matching rule: measure() выше оборачивает каждый публичный метод App\Service, а logFailure() срабатывает, когда один из них выбрасывает исключение. Раз это обычный класс, вам доступны внедрение через конструктор, приватное состояние, трейты и всё остальное, что есть в PHP.
Когда выполняется behavior
Заголовок раздела «Когда выполняется behavior»Атрибут behavior говорит, когда он выполняется относительно перехваченного вызова.
| Атрибут | Выполняется |
|---|---|
#[Before] |
Перед вызовом. Может изменить аргументы через setArguments(). |
#[After] |
После вызова, в том числе когда вызов выбрасывает исключение (как finally). |
#[AfterThrowing] |
Когда вызов выбрасывает исключение. Получает исключение вторым аргументом; после этого исключение выбрасывается дальше. |
#[Around] |
Вместо вызова, как это делает middleware. Сам решает, вызывать ли proceed(), а возвращаемое им значение становится результатом. |
Все четыре атрибута находятся в пространстве имён Go\Lang\Attribute и принимают matching rule в качестве аргумента.
namespace Aspect;
use Go\Aop\Aspect;use Go\Aop\Intercept\MethodInvocation;use Go\Lang\Attribute\Before;
class MonitorAspect implements Aspect{ #[Before('execution(public Example->*(*))')] public function beforeMethodExecution(MethodInvocation $invocation): void { echo 'Calling Before Interceptor for: ', $invocation, ' with arguments: ', json_encode($invocation->getArguments()), "<br>\n"; }}Behavior типа Before выполняется непосредственно перед исходным методом. Используйте его, чтобы проверить входные данные или права доступа. Чтобы изменить то, что получит исходный метод, замените аргументы:
#[Before('execution(public App\Service\UserService->rename(*))')]public function trimName(MethodInvocation $invocation): void{ $arguments = $invocation->getArguments(); $arguments[0] = trim($arguments[0]); $invocation->setArguments($arguments);}getArguments() возвращает аргументы по позициям, поэтому обращаться к ним нужно по индексу.
use Go\Aop\Intercept\MethodInvocation;use Go\Lang\Attribute\After;
#[After('execution(public App\Service\ImportService->run(*))')]public function releaseLock(MethodInvocation $invocation): void{ $this->lock->release();}Behavior типа After работает как блок finally: он выполняется и тогда, когда метод завершается нормально, и тогда, когда выбрасывает исключение. Используйте его, чтобы освобождать ресурсы или останавливать таймеры.
AfterThrowing
Заголовок раздела «AfterThrowing»use Go\Aop\Intercept\MethodInvocation;use Go\Lang\Attribute\AfterThrowing;
#[AfterThrowing('execution(public App\Service\*->*(*))')]public function logFailure(MethodInvocation $invocation, \Throwable $exception): void{ $this->logger->error($invocation . ' failed: ' . $exception->getMessage());}Behavior типа AfterThrowing выполняется, только когда вызов выбрасывает исключение. Исключение он получает вторым аргументом. После behavior фреймворк выбрасывает исключение дальше, так что вызывающий код по-прежнему его видит. Используйте его, чтобы логировать ошибки или отправлять оповещения.
use Go\Aop\Intercept\MethodInvocation;use Go\Lang\Attribute\Around;
#[Around('execution(public App\Service\*->*(*))')]public function measure(MethodInvocation $invocation): mixed{ $start = hrtime(true); try { return $invocation->proceed(); } finally { $this->logger->debug($invocation . ' took ' . (hrtime(true) - $start) . ' ns'); }}Behavior типа Around выполняется вместо вызова, как middleware в HTTP-стеке. Вызовом proceed() вы передаёте управление исходному коду, а всё, что вернёт behavior, становится результатом. Поэтому Around — самый мощный тип: он решает, выполнится ли исходный код вообще, может изменить аргументы перед proceed(), изменить возвращаемое значение и перехватить исключения. Используйте его для кеширования, транзакций и повторных попыток.
Если не вызвать proceed(), исходный метод не выполнится:
#[Around('execution(public App\Service\ReportService->build(*))')]public function cacheReport(MethodInvocation $invocation): mixed{ $key = $invocation . json_encode($invocation->getArguments());
return $this->reports[$key] ??= $invocation->proceed();}Call context
Заголовок раздела «Call context»Каждый behavior получает объект, описывающий перехваченный вызов: его аргументы, объект, на котором он выполняется, и proceed(), чтобы продолжить выполнение. Класс этого объекта зависит от того, что выбирает matching rule.
Справочник по call context
Заголовок раздела «Справочник по call context»| Класс | Передаётся для | Основные методы |
|---|---|---|
MethodInvocation |
execution() динамических и статических методов |
getThis(), getScope(), getMethod(), getArguments(), setArguments(), proceed() |
FunctionInvocation |
execution() функций в пространствах имён |
getFunction(), getArguments(), setArguments(), proceed() |
FieldAccess |
access() свойств |
getThis(), getField(), getAccessType(), getValue(), getValueToSet(), proceed() |
ConstructorInvocation |
initialization() |
getConstructor(), getArguments(), getThis() (null, пока объект не создан), proceed() |
Все они находятся в Go\Aop\Intercept. MethodInvocation можно использовать как строку — именно так примеры выше пишут его в сообщения логов.
Обобщённые типы
Заголовок раздела «Обобщённые типы»Эти классы объявляют типы @template, поэтому PHPStan и IDE знают типы getThis() и proceed(). Укажите конкретные типы в docblock вашего behavior:
use App\Model\Order;use App\Service\OrderService;use Go\Aop\Intercept\MethodInvocation;use Go\Lang\Attribute\Around;
/** * @param MethodInvocation<OrderService, Order> $invocation */#[Around('execution(public App\Service\OrderService->place(*))')]public function auditOrder(MethodInvocation $invocation): Order{ $order = $invocation->proceed(); // … return $order;}Здесь MethodInvocation<OrderService, Order> сообщает анализатору, что getThis() — это OrderService, а proceed() возвращает Order.
Как behaviors становятся middleware
Заголовок раздела «Как behaviors становятся middleware»В подключении behavior нет никакой магии. Для каждого перехваченного метода фреймворк генерирует обычную цепочку middleware. На каждый behavior ссылается замыкание, созданное с помощью синтаксиса first-class callable прямо на экземпляре behavior class:
static $__joinPoint = InterceptorInjector::forMethod( self::class, 'doSomething', [ Interceptor::before(The::aspect(MonitorAspect::class)->beforeMethodExecution(...)), ], $this->doSomethingOriginalAlias(...),);The::aspect() получает экземпляр behavior class из контейнера ядра, а ->beforeMethodExecution(...) — это написанный вами метод behavior. По нему можно перейти Ctrl-кликом в IDE, поставить внутри точку останова и пройти сгенерированный код по шагам, как будто он написан вручную. Call contexts создаются во время компиляции и кешируются в сгенерированном коде, поэтому во время выполнения нет ни рефлексии, ни разбора атрибутов. Подробнее о сгенерированном коде — на странице Debuggable.
Behaviors, зарегистрированные в контейнере как обычные замыкания, а не как методы behavior class, подключаются через ленивый аксессор The::advice(). Он находит зарегистрированную запись по её идентификатору и разворачивает её до самого замыкания:
Interceptor::around(The::advice('advisor.Demo\Aspect\DynamicMethodsAspect->aroundMagicMethods')),Matching rules
Заголовок раздела «Matching rules»Matching rule — это выражение, которое выбирает, где выполняется behavior: при выполнении методов, обращениях к свойствам, вызовах функций или создании объектов. Оно передаётся аргументом атрибута behavior:
#[Before('execution(public App\Service->save(*))')]В песочнице можно опробовать правила на PHP-файле; этот раздел — полный справочник.
Виды правил
Заголовок раздела «Виды правил»| Правило | Выбирает |
|---|---|
execution(modifiers Class->method(*)) |
Выполнение динамического метода |
execution(modifiers Class::method(*)) |
Выполнение статического метода |
execution(Namespace\function(*)) |
Вызовы системной функции из этого пространства имён |
access(modifiers Class->property) |
Чтение и запись свойства экземпляра |
within(ClassFilter) |
Все члены (методы и свойства) подходящих классов |
initialization(ClassFilter) |
Создание объекта через new |
staticinitialization(ClassFilter) |
Первую загрузку подходящих классов |
@execution(Attribute) |
Методы с этим атрибутом |
@access(Attribute) |
Свойства с этим атрибутом |
@within(Attribute) |
Все члены классов с этим атрибутом |
matchInherited() |
Только члены, унаследованные от родительского класса или импортированные из трейта; !matchInherited() исключает их |
matchReturningByReference() |
Методы и функции, объявленные как function &name(); !matchReturningByReference() исключает их |
$this->pointcutName |
Именованное правило, объявленное через #[Pointcut] на методе того же behavior class |
Aspect\Class->pointcutName |
Именованное правило другого behavior class |
Список аргументов всегда (*): аргументы не сопоставляются.
Обратите внимание на разделитель: -> выбирает динамические методы, :: — статические.
execution(public App\Service\OrderService->place(*))execution(public App\Util\Money::format(*))Чтобы перехватывать вызовы магических методов, подключите behavior к самому __call:
execution(public Foo->__call(*))Имена и подстановочные знаки
Заголовок раздела «Имена и подстановочные знаки»| Шаблон | Значение |
|---|---|
* |
Любые символы в пределах одной части имени, в том числе ни одного, никогда не пересекая \: get* (и просто get), *Service (и просто Service), App\*\Controller (ровно один уровень пространства имён между ними) |
** |
Любая глубина пространств имён: App\** — все классы внутри App, **->*(*) — все методы |
a|b |
Альтернативы в пределах одной части имени, например get*|is*. Они относятся к той части, в которой написаны: App\Cart|Order — это App\Cart или App\Order, но никогда не глобальный Order. Для классов из разных пространств имён объедините два правила через || |
Foo+ |
Сам Foo, его подклассы и реализации, а также классы, которые используют трейт Foo (напрямую или через родительский класс) |
Имена сопоставляются с учётом регистра. Пространства имён пишутся с одной обратной косой чертой; в PHP-строке в одинарных кавычках экранировать её не нужно.
execution(public **->save*(*))execution(public App\Repository\*Repository->find*|get*(*))execution(public App\Contract\Cacheable+->*(*))Модификаторы
Заголовок раздела «Модификаторы»Правила для методов и свойств принимают такие модификаторы:
public,protected,privatefinal,readonly- модификаторы асимметричной видимости
private(set)иprotected(set)
Альтернативы объединяются через |:
execution(public|protected App\Service->*(*))Модификаторы, разделённые пробелами, должны присутствовать все, а | связывает сильнее пробела. final public|protected выбирает final-методы, которые публичны или защищены. В одном шаблоне поддерживается одна группа альтернатив.
Статические свойства никогда не перехватываются, как и readonly-свойства и свойства, у которых уже есть хуки. Все случаи перечислены ниже, в разделе о перехвате свойств; причины — на странице Ограничения и переход на 4.0.
Возвращаемые типы
Заголовок раздела «Возвращаемые типы»Шаблон метода или функции может ограничивать объявленный возвращаемый тип:
execution(public App\Repo->find*(*): App\Entity|null)Объединения типов записываются через |, пересечения — через &, а ?Foo равнозначно Foo|null.
Комбинирование правил
Заголовок раздела «Комбинирование правил»| Оператор | Значение |
|---|---|
&& |
Подходят оба |
|| |
Подходит любое |
! |
Отрицание |
( ) |
Группировка |
within(App\**) && !execution(public **->__construct(*))Комментарии
Заголовок раздела «Комментарии»Комментарии начинаются с // и продолжаются до конца строки. Они помогают в длинных многострочных выражениях:
#[Around(' execution(public App\Service\**->*(*)) // every public service method && !matchReturningByReference() // skip function &name() && !matchInherited() // skip inherited and trait methods')]public function trace(MethodInvocation $invocation): mixed{ return $invocation->proceed();}Именованные правила
Заголовок раздела «Именованные правила»Объявите правило один раз и ссылайтесь на него из нескольких behaviors:
use Go\Aop\Aspect;use Go\Aop\Intercept\MethodInvocation;use Go\Lang\Attribute\After;use Go\Lang\Attribute\Before;use Go\Lang\Attribute\Pointcut;
class HealthyLiveAspect implements Aspect{ #[Pointcut('execution(public App\Human->eat(*))')] protected function humanEat(): void {}
#[Before('$this->humanEat')] public function washUpBeforeEat(MethodInvocation $invocation): void { /* ... */ }
#[After('$this->humanEat')] public function cleanTeethAfterEat(MethodInvocation $invocation): void { /* ... */ }}У метода с #[Pointcut] пустое тело: значение имеет только его атрибут. Внутри того же behavior class на него ссылаются как $this->humanEat. Из другого behavior class используйте имя объявляющего класса, например App\Aspect\HealthyLiveAspect->humanEat.
Правила по атрибутам
Заголовок раздела «Правила по атрибутам»@execution, @access и @within выбирают члены класса по PHP-атрибутам, которые на них стоят. Так вы помечаете код, которому нужен behavior, вместо того чтобы подбирать его по имени:
namespace App\Attribute;
#[\Attribute(\Attribute::TARGET_METHOD)]final class Cacheable {}use Go\Aop\Aspect;use Go\Aop\Intercept\MethodInvocation;use Go\Lang\Attribute\Around;
class CachingAspect implements Aspect{ #[Around('@execution(App\Attribute\Cacheable)')] public function cache(MethodInvocation $invocation): mixed { // … return $invocation->proceed(); }}@access(Attribute) делает то же самое для свойств, а @within(Attribute) выбирает все члены классов с этим атрибутом. Атрибуты скомпилированных классов копируются в сгенерированный код с исходными аргументами, так что чтение их во время выполнения работает как прежде. На этом правиле пример со страницы Кеширование результатов строит полноценный #[Cacheable(ttl: 600)].
Behaviors на свойствах
Заголовок раздела «Behaviors на свойствах»use Go\Aop\Intercept\FieldAccess;use Go\Aop\Intercept\FieldAccessType;use Go\Lang\Attribute\Around;
#[Around('access(public App\Entity\User->email)')]public function normalizeEmail(FieldAccess $access): mixed{ if ($access->getAccessType() === FieldAccessType::Write) { return strtolower($access->proceed()); }
return $access->proceed();}Правила access(...) перехватывают чтение и запись свойств экземпляра через нативные хуки свойств PHP 8.4 в сгенерированных прокси-классах. Behavior получает FieldAccess. При записи proceed() возвращает значение, которое будет сохранено, поэтому behavior типа Around может его изменить, как в примере.
Что можно перехватить:
- свойства, объявленные в самом скомпилированном классе, включая свойства, продвинутые через конструктор (в том числе
final, на PHP 8.5). Присваивание в конструкторе перехватывается как запись. - унаследованные от родительских классов публичные и защищённые свойства
Что пропускается:
- свойства
static,readonlyи свойства, у которых уже есть хуки - унаследованные от родительских классов свойства
final - унаследованные свойства
private
Для свойств с типом array прокси создаёт только хук &get по ссылке, без set. Благодаря этому косвенные изменения вроде array_push($this->items, ...) остаются допустимыми.
Когда Doctrine гидрирует или сохраняет сущность, она читает и пишет сырые значения свойств, поэтому behaviors на свойствах выполняются только при обращениях из вашего собственного кода. Настройка Doctrine описана на странице Интеграции, обзор — на странице о хуках свойств.
Class extensions
Заголовок раздела «Class extensions»use App\Model\JsonSerializableTrait;use Go\Aop\Aspect;use Go\Lang\Attribute\DeclareParents;
class SerializableAspect implements Aspect{ #[DeclareParents('within(App\Model\*)', interfaceName: \JsonSerializable::class, traitName: JsonSerializableTrait::class)] protected null $jsonSerializable;}namespace App\Model;
trait JsonSerializableTrait{ public function jsonSerialize(): mixed { return get_object_vars($this); }}Class extension меняет то, какие возможности предоставляют существующие классы, тогда как behavior меняет то, что происходит при выполнении их кода. #[DeclareParents] на свойстве behavior class добавляет подходящим классам интерфейс и реализующий его трейт. Здесь каждый класс в App\Model становится JsonSerializable, хотя ни один из них не редактировался. Это работает и для классов из пакетов Composer, см. страницу о class extensions.
Behaviors на вызовах функций
Заголовок раздела «Behaviors на вызовах функций»use Go\Aop\Intercept\FunctionInvocation;use Go\Lang\Attribute\Around;
#[Around('execution(App\Service\file_get_contents(*))')]public function logRead(FunctionInvocation $invocation): mixed{ $this->logger->debug('Reading ' . $invocation->getArguments()[0]);
return $invocation->proceed();}execution(App\Service\file_get_contents(*)) перехватывает вызовы file_get_contents() из кода в пространстве имён App\Service. Behavior получает FunctionInvocation.
Прокси перехваченных функций генерируются с declare(strict_types=1), по одному файлу на пространство имён. Аргументы приводятся по режиму вызывающего файла ещё до входа в прокси.
Создание объектов
Заголовок раздела «Создание объектов»use Go\Aop\Intercept\ConstructorInvocation;use Go\Lang\Attribute\Around;
#[Around('initialization(App\Model\Order)')]public function trackOrderCreation(ConstructorInvocation $invocation): mixed{ $order = $invocation->proceed(); // … return $order;}initialization(App\Model\Order) перехватывает new Order(...) в скомпилированных файлах. Behavior получает ConstructorInvocation. Его getThis() возвращает null, пока объект не создан.
staticinitialization(App\Model\*) выполняется один раз, после загрузки класса.
Регистрация behavior classes
Заголовок раздела «Регистрация behavior classes»Behavior classes — это сервисы контейнера ядра. Регистрируйте их в configureAop() вашего ядра, лучше всего как отложенные сервисы:
use Aspect\MonitorAspect;use Go\Core\AspectContainer;use Go\Core\AspectKernel;
class ApplicationAspectKernel extends AspectKernel{ protected function configureAop(AspectContainer $container): void { // Deferred (recommended): constructed on first use $container->addLazyService(MonitorAspect::class, static fn() => new MonitorAspect());
// Eager alternative: // $container->add(MonitorAspect::class, new MonitorAspect()); }}addLazyService() регистрирует фабрику. Compile step никогда не создаёт экземпляры behavior classes: каждый из них создаётся, когда впервые выполняется один из его behaviors, в виде нативного ленивого объекта PHP 8.4. add() регистрирует уже созданный вами экземпляр.
Зависимости
Заголовок раздела «Зависимости»Фабрика получает контейнер ядра — AspectContainer. Это PSR-11-контейнер, поэтому из него можно получить зависимости behavior class:
use Go\Core\AspectContainer;use Psr\Log\LoggerInterface;
$container->addLazyService( ServiceAspect::class, static fn(AspectContainer $c) => new ServiceAspect($c->getService(LoggerInterface::class)),);Сервисы собственного PSR-11-контейнера вашего приложения становятся доступны, как только вы подключите его к контейнеру ядра через setDelegate(). Мосты (bridges) для Symfony, Laravel и Yii3 регистрируют behavior classes за вас; см. Интеграции. Параметры ядра описаны на странице Конфигурация и CLI.
Унаследованные методы
Заголовок раздела «Унаследованные методы»Behavior выполняется один раз на каждое выполнение метода, сколько бы классов иерархии ни было скомпилировано. Метод, который скомпилированный класс только наследует, перехватывается в ближайшем скомпилированном предке, где его выбирает правило (вплоть до класса, объявившего метод); подкласс наследует этот перехваченный метод и ничего не переопределяет.
Если такого предка нет — например, родительский класс лежит вне includePaths или правило его не выбирает, — подкласс перехватывает унаследованный метод сам.
Чтобы ограничить правило членами, которые класс объявляет сам, добавьте !matchInherited(). Оно исключает члены, унаследованные от родительского класса, и члены, импортированные из трейта.
Ограничения
Заголовок раздела «Ограничения»Некоторые виды методов не могут получить behavior или работают с ним иначе. Полный список с причинами — на странице Ограничения и переход на 4.0. Вкратце:
- Возврат по ссылке. Метод или функцию, объявленные как
function &name(), перехватить нельзя; их компиляция завершается сWeavingException. Исключите такие методы из широкого правила через&& !matchReturningByReference(). - Методы трейтов с
#[\Override]. Метод, который класс импортирует из трейта и на котором стоит#[\Override], нельзя перехватить в этом классе; его компиляция завершается сWeavingException. Исключите его через&& !matchInherited()или подключите behavior к самому трейту, напримерexecution(public HelloTrait->hello(*)), — это действует во всех классах, использующих трейт. - Генераторы. Для метода, содержащего
yield, behavior выполняется в момент вызова метода, аproceed()возвращает объектGenerator. Значения, которые выдаёт генератор, behavior не видит. - Аргументы.
getArguments()возвращает аргументы по позициям. Вариативный параметр по ссылке (&...$values) передаётся в исходный метод по значению. #[\SensitiveParameter]. Два внутренних фрейма между call context и исходным методом всё ещё содержат массив аргументов вThrowable::getTrace(). Сzend.exception_ignore_args=On, значением по умолчанию для продакшена, аргументов нет ни в одном фрейме.- Свойства. Статические, readonly-свойства и свойства, у которых уже есть хуки, не перехватываются, как и унаследованные свойства
finalиprivate.
© 2026 Alexander Lisachenko
