Ein Glaswürfel mit einem warmgelben Lichtpunkt im Inneren, berührt von zwei dünnen Strahlen.
Funktion · Property-Hooks

Jeden Lese- und Schreibzugriff auf Properties abfangen.

Validieren, normalisieren und auditieren Sie Property-Zugriffe, ohne Getter, Setter oder magische Methoden hinzuzufügen. Hängen Sie Verhalten direkt an Properties, und Ihr Code bleibt lesbar und statisch analysierbar.

Fast* jede Property

Was sich abfangen lässt

Lese- und Schreibzugriffe auf die Properties, die Sie deklarieren, laufen durch ein Verhalten: Validieren, normalisieren oder auditieren Sie sie. Beim Schreiben gibt proceed() den Wert zurück, der gespeichert wird, sodass ein Verhalten um den Schreibzugriff ihn ändern kann, bevor er ankommt.

  • Public, protected und private Properties, die in der Klasse deklariert sind
  • Per Konstruktor promotete und finale Properties: Die Zuweisung im Konstruktor ist ein Schreibzugriff
  • Public und protected Properties, die von einer Elternklasse geerbt sind
  • Asymmetrische Sichtbarkeit (private(set)) und Attribute bleiben erhalten
  • Array-Properties funktionieren weiter mit array_push(), über &get-Hooks
  • Nicht unterstützt: *Statische, readonly und bereits mit Hooks versehene Properties bleiben unberührt: PHP erlaubt dort keine Hooks.
src/Aspect/UserAspect.phpbeim Schreiben normalisieren
#[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();}
So funktioniert es

Native PHP-Hooks. Automatisch generiert.

Das Framework macht aus Ihrer Klasse gewöhnliche PHP-Dateien. Markierte Properties werden mit nativen get- und set-Hooks von PHP 8.4+ neu geschrieben, die bei jedem Zugriff auf die Property das angehängte Verhalten aufrufen.

Ihre Klasse

Zwei Properties tragen #[Auditable], das Attribut, nach dem das Audit-Verhalten unten sucht; die dritte nicht. Die Datei bleibt genau so, wie Sie sie geschrieben haben.

Customer.phpIhr 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;
        
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      

Kompilierter Quelltext

Ihr Klassenrumpf als Trait CustomerOriginalTrait. Jede markierte Property hinterlässt eine einzeilige Notiz, und alle anderen Zeilen behalten ihre Nummer für Xdebug.

CustomerOriginalTrait.phpkompiliert

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

Proxy-Klasse mit Hooks

Die Klasse, die PHP lädt: Ihr Klassenname, der Trait und die markierten Properties, neu deklariert mit Attribut, Typ und Standardwert, dazu get- und set-Hooks. Jeder Hook leitet den Zugriff durch die Audit-Middleware.

Customer.phpgeneriert

        
        
        <?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
        gleicher Klassenname
        
        
      
        
        
        {
        
        
        
      
        
        
            use CustomerOriginalTrait;
        der Rest Ihrer Klasse
        
        
      
        
        
            #[\App\Attribute\Auditable]
        Attribut bleibt
        
        
      
        
        
            public string $email = '' {
        native PHP-8.4-Hooks
        
        
      
        
        
                get {
        
        
        
      
        
        
                    /** @var FieldAccess<self, string> $__joinPoint */
        typisiert für PHPStan und IDEs
        
        
      
        
        
                    static $__joinPoint = InterceptorInjector::forProperty(
        
        
        
      
        
        
                        self::class,
        
        
        
      
        
        
                        'email',
        
        
        
      
        
        
                        [
        
        
        
      
        
        
                            Interceptor::around(The::aspect(AuditAspect::class)->auditWrite(...)),
        Ihr Audit-Verhalten
        
        
      
        
        
                        ],
        
        
        
      
        
        
                    );
        
        
        
      
        
        
                    return $__joinPoint->read($this, $this->email);
        Lesen geht durch
        
        
      
        
        
                }
        
        
        
      
        
        
                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);
        Schreiben läuft durchs Verhalten
        
        
      
        
        
                }
        
        
        
      
        
        
            }
        
        
        
      
        
        
            #[\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);
        
        
        
      
        
        
                }
        
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      
Audit-Trail

Jede Änderung auditieren, mit einem Attribut

Markieren Sie die wichtigen Properties mit #[Auditable]. Das Audit-Verhalten hängt an jeder von ihnen als dynamische Middleware: Jeder Schreibzugriff wird mit Property-Namen, altem und neuem Wert protokolliert, egal woher er kommt.

  • Jeder Schreibzugriff auf eine markierte Property, aus beliebigem Code: von außen, aus der Klasse, im Konstruktor
  • Der alte und der neue Wert, bevor der Schreibzugriff ankommt
  • Nicht markierte Properties und Lesezugriffe kosten nichts extra
  • Die Entity behält einfache public Properties: keine Setter, kein __set()
src/Attribute/Auditable.phpIhr Attribut
#[\Attribute(\Attribute::TARGET_PROPERTY)]final class Auditable {}
Was protokolliert wirdVerwendung
$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.phpIhre Entity

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

        
        
        <?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)')]
        jede #[Auditable]-Property
        
        
      
        
        
            public function auditWrite(FieldAccess $access): mixed
        
        
        
      
        
        
            {
        
        
        
      
        
        
                if ($access->getAccessType() === FieldAccessType::Write) {
        nur Schreiben
        
        
      
        
        
                    $this->audit->info('Property changed', [
        
        
        
      
        
        
                        'property' => $access->getField()->name,
        
        
        
      
        
        
                        'from'     => $access->getValue(),
        
        
        
      
        
        
                        'to'       => $access->getValueToSet(),
        
        
        
      
        
        
                    ]);
        
        
        
      
        
        
                }
        
        
        
      
        
        
         
        
        
        
      
        
        
                return $access->proceed();
        der Wert kommt an
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      

Schnell genug, um es anzulassen

Messwerte und die vollständige Liste der Regeln finden Sie in docs/advices.md und docs/performance.md.

  • Magie0kein __get oder __set: IDEs und PHPStan sehen echte Properties
  • nativPHP 8.4kompiliert in die Property-Hooks der Sprache selbst
Playground

Wählen Sie Ihre eigenen Properties aus

Beginnen Sie mit @access(App\Attribute\Auditable) und ändern Sie es dann: Jede Property, die der Ausdruck erreicht, leuchtet im Playground auf, Zeile für Zeile.

Pointcut ausprobieren