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

Поведения и правила выбора

Полный справочник по поведениям — динамическим промежуточным слоям, которые фреймворк выполняет вокруг вашего кода, — и по правилам выбора, которые определяют, где они применяются.

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

На этой странице собрано всё, что вы пишете при работе с фреймворком: 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 (внедрение) Интерфейс и трейт, добавленные к существующим классам
src/Aspect/ServiceAspect.php
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 говорит, когда он выполняется относительно перехваченного вызова.

Атрибут Выполняется
#[Before] Перед вызовом. Может изменить аргументы через setArguments().
#[After] После вызова, в том числе когда вызов выбрасывает исключение (как finally).
#[AfterThrowing] Когда вызов выбрасывает исключение. Получает исключение вторым аргументом; после этого исключение выбрасывается дальше.
#[Around] Вместо вызова, как это делает middleware. Сам решает, вызывать ли proceed(), а возвращаемое им значение становится результатом.

Все четыре атрибута находятся в пространстве имён Go\Lang\Attribute и принимают matching rule в качестве аргумента.

src/Aspect/MonitorAspect.php
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: он выполняется и тогда, когда метод завершается нормально, и тогда, когда выбрасывает исключение. Используйте его, чтобы освобождать ресурсы или останавливать таймеры.

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();
}

Каждый behavior получает объект, описывающий перехваченный вызов: его аргументы, объект, на котором он выполняется, и proceed(), чтобы продолжить выполнение. Класс этого объекта зависит от того, что выбирает matching rule.

Класс Передаётся для Основные методы
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.

В подключении 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 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, private
  • final, 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:

src/Aspect/HealthyLiveAspect.php
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, вместо того чтобы подбирать его по имени:

src/Attribute/Cacheable.php
namespace App\Attribute;
#[\Attribute(\Attribute::TARGET_METHOD)]
final class Cacheable {}
src/Aspect/CachingAspect.php
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)].

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 описана на странице Интеграции, обзор — на странице о хуках свойств.

src/Aspect/SerializableAspect.php
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;
}
src/Model/JsonSerializableTrait.php
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.

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 — это сервисы контейнера ядра. Регистрируйте их в configureAop() вашего ядра, лучше всего как отложенные сервисы:

app/ApplicationAspectKernel.php
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