Стеклянный куб с тёплой жёлтой точкой света внутри, которого касаются два тонких луча.
Возможность · Хуки свойств

Перехват каждого чтения и записи свойства.

Проверяйте, нормализуйте и аудируйте доступ к свойствам без геттеров, сеттеров и магических методов. Подключайте поведения прямо к свойствам, а код остаётся читаемым и пригодным для статического анализа.

Почти* любое свойство

Что можно перехватить

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

  • Публичные, защищённые и приватные свойства, объявленные в классе
  • Свойства из конструктора (promoted) и final-свойства: присваивание в конструкторе — это запись
  • Публичные и защищённые свойства, унаследованные от родительского класса
  • Асимметричная видимость (private(set)) и атрибуты сохраняются
  • Свойства-массивы по-прежнему работают с array_push() через хуки &get
  • Не поддерживается: *Статические, readonly-свойства и свойства, у которых уже есть хуки, остаются без изменений: PHP не допускает для них хуков.
src/Aspect/UserAspect.phpнормализация при записи
#[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();}
Как это работает

Нативные хуки PHP. Генерируются автоматически.

Фреймворк превращает ваш класс в обычные PHP-файлы. Отмеченные свойства переписываются с нативными хуками get и set из PHP 8.4+, которые вызывают подключённые поведения при каждом обращении к свойству.

Ваш класс

Два свойства помечены #[Auditable] — атрибутом, который ищет поведение аудита ниже; третье — нет. Файл остаётся ровно таким, каким вы его написали.

Customer.phpваш код

        
        
        <?php
        
        
        
      
        
        
         
        
        
        
      
        
        
        declare(strict_types=1);
        
        
        
      
        
        
         
        
        
        
      
        
        
        namespace App\Entity;
        
        
        
      
        
        
         
        
        
        
      
        
        
        use App\Attribute\Auditable;
        
        
        
      
        
        
         
        
        
        
      
        
        
        class Customer
        
        
        
      
        
        
        {
        
        
        
      
        
        
            #[Auditable]
        
        
        
      
        
        
            public string $email = '';
        
        
        
      
        
        
         
        
        
        
      
        
        
            #[Auditable]
        
        
        
      
        
        
            public string $plan = 'free';
        
        
        
      
        
        
         
        
        
        
      
        
        
            public string $displayName = '';
        
        
        
      
        
        
         
        
        
        
      
        
        
            public function upgrade(string $plan): void
        
        
        
      
        
        
            {
        
        
        
      
        
        
                $this->plan = $plan;
        
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      

Скомпилированный исходник

Тело вашего класса в виде трейта CustomerOriginalTrait. На месте каждого отмеченного свойства остаётся однострочная пометка, а все остальные строки сохраняют свои номера для Xdebug.

CustomerOriginalTrait.phpскомпилировано

        
        
        <?php
        
        
        
      
        
        
         
        
        
        
      
        
        
        declare(strict_types=1);
        
        
        
      
        
        
         
        
        
        
      
        
        
        namespace App\Entity;
        
        
        
      
        
        
         
        
        
        
      
        
        
        use App\Attribute\Auditable;
        
        
        
      
        
        
         
        
        
        
      
        
        
        trait CustomerOriginalTrait
        было: class Customer
        
        
      
        
        
        {
        
        
        
      
        
        
            /* Moved by weaving interceptor to the {@see App\Entity\Customer->email} */
        
        
        
      
        
        
         
        
        
        
      
        
        
         
        
        
        
      
        
        
            /* Moved by weaving interceptor to the {@see App\Entity\Customer->plan} */
        
        
        
      
        
        
         
        
        
        
      
        
        
         
        
        
        
      
        
        
            public string $displayName = '';
        
        
        
      
        
        
         
        
        
        
      
        
        
            public function upgrade(string $plan): void
        
        
        
      
        
        
            {
        
        
        
      
        
        
                $this->plan = $plan;
        
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      
        
        
        include_once AOP_CACHE_DIR . '/src/Entity/Customer.php';
        
        
        
      

Прокси-класс с хуками

Класс, который загружает PHP: имя вашего класса, трейт и отмеченные свойства, объявленные заново с атрибутом, типом и значением по умолчанию, плюс хуки get и set. Каждый хук пропускает обращение через middleware аудита.

Customer.phpсгенерировано

        
        
        <?php
        
        
        
      
        
        
        declare(strict_types=1);
        
        
        
      
        
        
        namespace App\Entity;
        
        
        
      
        
        
         
        
        
        
      
        
        
        use Go\Aop\Framework\InterceptorInjector;
        
        
        
      
        
        
        use Go\Aop\Framework\Interceptor;
        
        
        
      
        
        
        use Go\Aop\Framework\The;
        
        
        
      
        
        
        use Go\Aop\Intercept\FieldAccess;
        
        
        
      
        
        
        use App\Aspect\AuditAspect;
        
        
        
      
        
        
        use App\Attribute\Auditable;
        
        
        
      
        
        
        class Customer implements \Go\Aop\Proxy
        то же имя класса
        
        
      
        
        
        {
        
        
        
      
        
        
            use CustomerOriginalTrait;
        остальной ваш класс
        
        
      
        
        
            #[\App\Attribute\Auditable]
        атрибут сохранён
        
        
      
        
        
            public string $email = '' {
        нативные хуки PHP 8.4
        
        
      
        
        
                get {
        
        
        
      
        
        
                    /** @var FieldAccess<self, string> $__joinPoint */
        типы для PHPStan и IDE
        
        
      
        
        
                    static $__joinPoint = InterceptorInjector::forProperty(
        
        
        
      
        
        
                        self::class,
        
        
        
      
        
        
                        'email',
        
        
        
      
        
        
                        [
        
        
        
      
        
        
                            Interceptor::around(The::aspect(AuditAspect::class)->auditWrite(...)),
        ваше поведение аудита
        
        
      
        
        
                        ],
        
        
        
      
        
        
                    );
        
        
        
      
        
        
                    return $__joinPoint->read($this, $this->email);
        чтение проходит напрямую
        
        
      
        
        
                }
        
        
        
      
        
        
                set {
        
        
        
      
        
        
                    /** @var FieldAccess<self, string> $__joinPoint */
        
        
        
      
        
        
                    static $__joinPoint = InterceptorInjector::forProperty(
        
        
        
      
        
        
                        self::class,
        
        
        
      
        
        
                        'email',
        
        
        
      
        
        
                        [
        
        
        
      
        
        
                            Interceptor::around(The::aspect(AuditAspect::class)->auditWrite(...)),
        
        
        
      
        
        
                        ],
        
        
        
      
        
        
                    );
        
        
        
      
        
        
                    $this->email = $__joinPoint->write($this, $value, $this->email);
        запись идёт через поведение
        
        
      
        
        
                }
        
        
        
      
        
        
            }
        
        
        
      
        
        
            #[\App\Attribute\Auditable]
        
        
        
      
        
        
            public string $plan = 'free' {
        
        
        
      
        
        
                get {
        
        
        
      
        
        
                    /** @var FieldAccess<self, string> $__joinPoint */
        
        
        
      
        
        
                    static $__joinPoint = InterceptorInjector::forProperty(
        
        
        
      
        
        
                        self::class,
        
        
        
      
        
        
                        'plan',
        
        
        
      
        
        
                        [
        
        
        
      
        
        
                            Interceptor::around(The::aspect(AuditAspect::class)->auditWrite(...)),
        
        
        
      
        
        
                        ],
        
        
        
      
        
        
                    );
        
        
        
      
        
        
                    return $__joinPoint->read($this, $this->plan);
        
        
        
      
        
        
                }
        
        
        
      
        
        
                set {
        
        
        
      
        
        
                    /** @var FieldAccess<self, string> $__joinPoint */
        
        
        
      
        
        
                    static $__joinPoint = InterceptorInjector::forProperty(
        
        
        
      
        
        
                        self::class,
        
        
        
      
        
        
                        'plan',
        
        
        
      
        
        
                        [
        
        
        
      
        
        
                            Interceptor::around(The::aspect(AuditAspect::class)->auditWrite(...)),
        
        
        
      
        
        
                        ],
        
        
        
      
        
        
                    );
        
        
        
      
        
        
                    $this->plan = $__joinPoint->write($this, $value, $this->plan);
        
        
        
      
        
        
                }
        
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      
Журнал аудита

Аудит каждого изменения одним атрибутом

Отметьте важные свойства атрибутом #[Auditable]. Поведение аудита подключается к каждому из них как динамический middleware: каждая запись фиксируется с именем свойства, старым и новым значением, откуда бы она ни пришла.

  • Каждая запись отмеченного свойства из любого кода: снаружи, внутри класса, в конструкторе
  • Старое и новое значение — до того, как запись выполнится
  • Неотмеченные свойства и чтения не стоят ничего лишнего
  • Сущность сохраняет простые публичные свойства: без сеттеров, без __set()
src/Attribute/Auditable.phpваш атрибут
#[\Attribute(\Attribute::TARGET_PROPERTY)]final class Auditable {}
Что записываетсяиспользование
$customer->plan = 'pro';         // audit: plan, from "free" to "pro"$customer->upgrade('team');      // audit: plan, from "pro" to "team"$customer->displayName = 'Ann';  // no record: no #[Auditable]echo $customer->email;           // reads pass through untouched
Customer.phpваша сущность

        
        
        <?php
        
        
        
      
        
        
         
        
        
        
      
        
        
        declare(strict_types=1);
        
        
        
      
        
        
         
        
        
        
      
        
        
        namespace App\Entity;
        
        
        
      
        
        
         
        
        
        
      
        
        
        use App\Attribute\Auditable;
        
        
        
      
        
        
         
        
        
        
      
        
        
        class Customer
        
        
        
      
        
        
        {
        
        
        
      
        
        
            #[Auditable]
        под аудитом
        
        
      
        
        
            public string $email = '';
        
        
        
      
        
        
         
        
        
        
      
        
        
            #[Auditable]
        под аудитом
        
        
      
        
        
            public string $plan = 'free';
        
        
        
      
        
        
         
        
        
        
      
        
        
            public string $displayName = '';
        без аудита
        
        
      
        
        
         
        
        
        
      
        
        
            public function upgrade(string $plan): void
        
        
        
      
        
        
            {
        
        
        
      
        
        
                $this->plan = $plan;
        
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      
AuditAspect.phpповедение аудита

        
        
        <?php
        
        
        
      
        
        
         
        
        
        
      
        
        
        namespace App\Aspect;
        
        
        
      
        
        
         
        
        
        
      
        
        
        use Go\Aop\Aspect;
        
        
        
      
        
        
        use Go\Aop\Intercept\FieldAccess;
        
        
        
      
        
        
        use Go\Aop\Intercept\FieldAccessType;
        
        
        
      
        
        
        use Go\Lang\Attribute\Around;
        
        
        
      
        
        
        use Psr\Log\LoggerInterface;
        
        
        
      
        
        
         
        
        
        
      
        
        
        final class AuditAspect implements Aspect
        
        
        
      
        
        
        {
        
        
        
      
        
        
            public function __construct(private LoggerInterface $audit) {}
        
        
        
      
        
        
         
        
        
        
      
        
        
            #[Around('@access(App\Attribute\Auditable)')]
        каждое свойство с #[Auditable]
        
        
      
        
        
            public function auditWrite(FieldAccess $access): mixed
        
        
        
      
        
        
            {
        
        
        
      
        
        
                if ($access->getAccessType() === FieldAccessType::Write) {
        только запись
        
        
      
        
        
                    $this->audit->info('Property changed', [
        
        
        
      
        
        
                        'property' => $access->getField()->name,
        
        
        
      
        
        
                        'from'     => $access->getValue(),
        
        
        
      
        
        
                        'to'       => $access->getValueToSet(),
        
        
        
      
        
        
                    ]);
        
        
        
      
        
        
                }
        
        
        
      
        
        
         
        
        
        
      
        
        
                return $access->proceed();
        значение записано
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      

Достаточно быстро, чтобы не выключать

Измерения и полный список правил — в docs/advices.md и docs/performance.md.

  • магии0никаких __get и __set: IDE и PHPStan видят настоящие свойства
  • нативноPHP 8.4встроено в собственные хуки свойств языка
Песочница

Выберите свои свойства

Начните с pointcut (среза) @access(App\Attribute\Auditable) и измените его: каждое свойство, которое он выбирает, подсвечивается в песочнице, строка за строкой.

Проверить pointcut