Un cube de verre renfermant un point de lumière jaune chaud, effleuré par deux fins faisceaux.
Fonctionnalité · Property hooks

Interceptez chaque lecture et chaque écriture de propriété.

Validez, normalisez et auditez l’accès aux propriétés sans ajouter de getters, de setters ni de méthodes magiques. Attachez des comportements directement aux propriétés : votre code reste lisible et analysable statiquement.

Presque* toutes les propriétés

Ce que vous pouvez intercepter

Les lectures et les écritures des propriétés que vous déclarez passent par un comportement : validez-les, normalisez-les ou auditez-les. Lors d’une écriture, proceed() renvoie la valeur qui sera stockée : un comportement placé autour de l’écriture peut donc la modifier avant qu’elle ne soit enregistrée.

  • Propriétés publiques, protégées et privées déclarées dans la classe
  • Propriétés promues par le constructeur et propriétés finales : l’affectation dans le constructeur est une écriture
  • Propriétés publiques et protégées héritées d’une classe parente
  • La visibilité asymétrique (private(set)) et les attributs restent intacts
  • Les propriétés tableau fonctionnent toujours avec array_push(), grâce aux hooks &get
  • Non pris en charge : *Les propriétés statiques, readonly et déjà dotées de hooks sont laissées de côté : PHP n’autorise pas de hooks sur elles.
src/Aspect/UserAspect.phpnormalisation à l’écriture
#[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();}
Fonctionnement

Des hooks PHP natifs. Générés automatiquement.

Le framework transforme votre classe en fichiers PHP ordinaires. Les propriétés marquées sont réécrites avec des hooks get et set natifs de PHP 8.4+, qui invoquent les comportements attachés à chaque accès à la propriété.

Votre classe

Deux propriétés portent #[Auditable], l’attribut que recherche le comportement d’audit ci-dessous ; la troisième non. Le fichier reste exactement tel que vous l’avez écrit.

Customer.phpvotre code

        
        
        <?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;
        
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      

Source compilée

Le corps de votre classe, sous la forme du trait CustomerOriginalTrait. Chaque propriété marquée laisse une note d’une ligne, et toutes les autres lignes gardent leur numéro pour Xdebug.

CustomerOriginalTrait.phpcompilé

        
        
        <?php
        
        
        
      
        
        
         
        
        
        
      
        
        
        declare(strict_types=1);
        
        
        
      
        
        
         
        
        
        
      
        
        
        namespace App\Entity;
        
        
        
      
        
        
         
        
        
        
      
        
        
        use App\Attribute\Auditable;
        
        
        
      
        
        
         
        
        
        
      
        
        
        trait CustomerOriginalTrait
        avant : 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';
        
        
        
      

Classe proxy avec hooks

La classe que PHP charge : le nom de votre classe, le trait, et les propriétés marquées déclarées à nouveau avec leur attribut, leur type et leur valeur par défaut, plus des hooks get et set. Chaque hook fait passer l’accès par le middleware d’audit.

Customer.phpgénéré

        
        
        <?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
        même nom de classe
        
        
      
        
        
        {
        
        
        
      
        
        
            use CustomerOriginalTrait;
        le reste de votre classe
        
        
      
        
        
            #[\App\Attribute\Auditable]
        attribut conservé
        
        
      
        
        
            public string $email = '' {
        hooks natifs PHP 8.4
        
        
      
        
        
                get {
        
        
        
      
        
        
                    /** @var FieldAccess<self, string> $__joinPoint */
        typé pour PHPStan et les IDE
        
        
      
        
        
                    static $__joinPoint = InterceptorInjector::forProperty(
        
        
        
      
        
        
                        self::class,
        
        
        
      
        
        
                        'email',
        
        
        
      
        
        
                        [
        
        
        
      
        
        
                            Interceptor::around(The::aspect(AuditAspect::class)->auditWrite(...)),
        votre comportement d’audit
        
        
      
        
        
                        ],
        
        
        
      
        
        
                    );
        
        
        
      
        
        
                    return $__joinPoint->read($this, $this->email);
        les lectures passent
        
        
      
        
        
                }
        
        
        
      
        
        
                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);
        les écritures passent par le comportement
        
        
      
        
        
                }
        
        
        
      
        
        
            }
        
        
        
      
        
        
            #[\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);
        
        
        
      
        
        
                }
        
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      
Piste d’audit

Auditez chaque modification avec un seul attribut

Marquez les propriétés qui comptent avec #[Auditable]. Le comportement d’audit est attaché à chacune d’elles comme middleware dynamique : chaque écriture est enregistrée avec le nom de la propriété, l’ancienne valeur et la nouvelle, d’où que vienne l’écriture.

  • Chaque écriture d’une propriété marquée, depuis n’importe quel code : l’extérieur, l’intérieur de la classe, le constructeur
  • L’ancienne et la nouvelle valeur, avant que l’écriture ne soit appliquée
  • Les propriétés non marquées et les lectures ne coûtent rien de plus
  • L’entité garde de simples propriétés publiques : pas de setters, pas de __set()
src/Attribute/Auditable.phpvotre attribut
#[\Attribute(\Attribute::TARGET_PROPERTY)]final class Auditable {}
Ce qui est enregistréutilisation
$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.phpvotre entité

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

        
        
        <?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)')]
        chaque propriété #[Auditable]
        
        
      
        
        
            public function auditWrite(FieldAccess $access): mixed
        
        
        
      
        
        
            {
        
        
        
      
        
        
                if ($access->getAccessType() === FieldAccessType::Write) {
        écritures seulement
        
        
      
        
        
                    $this->audit->info('Property changed', [
        
        
        
      
        
        
                        'property' => $access->getField()->name,
        
        
        
      
        
        
                        'from'     => $access->getValue(),
        
        
        
      
        
        
                        'to'       => $access->getValueToSet(),
        
        
        
      
        
        
                    ]);
        
        
        
      
        
        
                }
        
        
        
      
        
        
         
        
        
        
      
        
        
                return $access->proceed();
        la valeur est écrite
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      

Assez rapide pour rester activé

Les mesures et la liste complète des règles se trouvent dans docs/advices.md et docs/performance.md.

  • méthode magique0ni __get ni __set : les IDE et PHPStan voient de vraies propriétés
  • natifPHP 8.4compilé dans les property hooks du langage lui-même
Playground

Sélectionnez vos propres propriétés

Partez de @access(App\Attribute\Auditable), puis modifiez-le : chaque propriété atteinte s’allume dans le playground, ligne par ligne.

Essayer votre pointcut