Un haz ámbar atraviesa tres paredes de vidrio oscuro.
Funcionalidad · Intercepta cualquier cosa

Ningún método queda fuera de alcance.

Intercepta lo que otros no pueden. Métodos public, protected, private, final, static, de enums y de clases readonly. El nuevo motor va más allá de los límites de la intercepción tradicional basada en proxies.

Tipos de advice

Cinco formas de aplicar el comportamiento.

Ejecuta lógica antes, después o alrededor de una llamada a un método. Gestiona excepciones, cambia el flujo de ejecución o añade nuevas capacidades, todo con comportamientos declarativos.

#[Before]

Runs before the method. It can check access, validate the arguments or replace them with setArguments().

Security checks · validation

public function check(MethodInvocation $invocation): void

#[After]

Runs after the method, also when it throws, like a finally block.

Audit trails · cleanup · metrics

public function audit(MethodInvocation $invocation): void

#[AfterThrowing]

Runs only when the method throws, and receives the exception. The exception is rethrown afterwards.

Error logging · alerts

public function alert(MethodInvocation $invocation, \Throwable $e): void

#[Around]

Runs instead of the method and decides whether to call proceed(). Its return value becomes the result.

Caching · transactions · timing

public function cache(MethodInvocation $invocation): mixed

#[DeclareParents]

An introduction adds an interface, and a trait that implements it, to every class the pointcut selects. It sits on a property of the behavior class, and the classes themselves don’t change.

JsonSerializable on models · marker interfaces

#[DeclareParents('within(App\Model\*)', interfaceName: \JsonSerializable::class, traitName: JsonSerializableTrait::class)] protected null $jsonSerializable;
Pointcuts

Elige qué recibe un comportamiento.

Apunta a métodos, propiedades y atributos con reglas de coincidencia expresivas. Mira exactamente qué selecciona cada regla.

Methods

execution() selects method calls: -> for instance methods, :: for static ones.

  1. Public methods

    execution(public App\Billing\Invoice->pay(*))

    The everyday case: one method of one class. Use * in the class or the method name to select many.

    SelectsInvoice->pay() · line 61

  2. Protected methods

    execution(protected App\Billing\Invoice->audit(*))

    Internal steps that subclasses and decorators were never meant to see.

    SelectsInvoice->audit() · line 79

  3. Static methods

    execution(public App\Billing\Invoice::issue(*))

    :: selects static methods: named constructors, factories, helpers.

    SelectsInvoice::issue() · line 55

  4. Final methods

    execution(final public App\Billing\Invoice->total(*))

    Modifiers separated by spaces must all be present: final and public. The method stays final.

    SelectsInvoice->total() · line 74

  5. Private methods

    new in 4.0
    execution(private App\Billing\Invoice->recalculate(*))

    The method stays private. No subclass, no decorator, no change to the class.

    SelectsInvoice->recalculate() · line 84

  6. Trait methods

    execution(public App\Billing\HasNumber->number(*))

    Attach the behavior to the trait itself, and it runs in every class that uses the trait.

    SelectsHasNumber->number() · line 21

  7. Enum methods

    new in 4.0
    execution(public App\Billing\Status->label(*))

    Methods you declare on an enum. The built-in cases(), from() and tryFrom() are never intercepted.

    SelectsStatus->label() · line 13

Properties

access() selects reads and writes, woven into native PHP 8.4 property hooks.

  1. Public properties

    access(public App\Billing\Invoice->customerEmail)

    Every read and every write of the property, with no getter or setter in the class.

    SelectsInvoice->customerEmail · line 45

  2. Protected properties

    access(protected App\Billing\Invoice->notes)

    Writes from inside the class go through the middleware too, here the ones made by audit().

    SelectsInvoice->notes · line 49

  3. Private and promoted properties

    access(private App\Billing\Invoice->total)

    A constructor-promoted property counts: the assignment the constructor makes is intercepted as a write.

    SelectsInvoice->total (promoted) · line 53

  4. Asymmetric visibility

    access(private(set) App\Billing\Invoice->status)

    public private(set): anyone reads, only the class writes. The proxy keeps both visibilities.

    SelectsInvoice->status · line 47

  5. Final properties

    access(final public App\Billing\Invoice->currency)

    A final property declared in the class is intercepted like any other.

    SelectsInvoice->currency · line 51

  6. Every public property

    access(public App\Billing\Invoice->*)

    Readonly properties are left out, since PHP allows no hooks on them; so are static and already-hooked ones.

    SelectsInvoice->customerEmail · line 45Invoice->status · line 47Invoice->currency · line 51Invoice->id (promoted): readonly property, not intercepted

Attributes

Your own attributes: mark the code, and the pointcut follows the mark.

  1. On a class

    @within(App\Attribute\Monitored)

    Every method and property of each class marked #[Monitored], including the ones it takes from traits.

    SelectsInvoice->customerEmail · line 45Invoice->status · line 47Invoice->notes · line 49Invoice->currency · line 51Invoice->total (promoted) · line 53and 8 moreInvoice->issued: static property, not interceptedInvoice->id (promoted): readonly property, not intercepted

  2. On a method

    @execution(App\Attribute\Auditable)

    Every method marked #[Auditable], wherever you put the attribute next.

    SelectsInvoice->refund() · line 68

  3. On a property

    @access(App\Attribute\Auditable)

    Every property marked #[Auditable]: reads and writes.

    SelectsInvoice->customerEmail · line 45

Beyond members

Whole classes, PHP function calls, object creation and the first load of a class.

  1. Readonly classes

    within(App\Billing\Money)

    within() selects every member of a class. The methods of a readonly class are intercepted; its properties are readonly, so they are not.

    SelectsMoney->__construct() · line 29Money->add() · line 31Money->cents (promoted): readonly property, not intercepted

  2. System function calls

    execution(App\Billing\file_put_contents(*))

    Calls of a PHP function from code in your namespace, written without a leading backslash.

    Selectsfile_put_contents() call · line 71

  3. Object creation: initialization

    initialization(App\Billing\Money)

    Every new Money(…) in woven code: count, log or check the objects your code creates.

    Selectsnew Money(…) · line 33new Money(…) · line 70

  4. First class load: staticinitialization

    staticinitialization(App\Billing\*)

    Runs once per class, right after the class is loaded. Here: the enum and both classes, but not the trait.

    Selectsenum Status loads · line 8class Money loads · line 27class Invoice loads · line 38

Invoice.phpexample

        
        
        <?php
        
        
        
      
        
        
         
        
        
        
      
        
        
        namespace App\Billing;
        
        
        
      
        
        
         
        
        
        
      
        
        
        use App\Attribute\Auditable;
        
        
        
      
        
        
        use App\Attribute\Monitored;
        
        
        
      
        
        
         
        
        
        
      
        
        
        enum Status: string
        
        
        
      
        
        
        {
        
        
        
      
        
        
            case Draft = 'draft';
        
        
        
      
        
        
            case Paid = 'paid';
        
        
        
      
        
        
         
        
        
        
      
        
        
            public function label(): string
        
        
        
      
        
        
            {
        
        
        
      
        
        
                return ucfirst($this->value);
        
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      
        
        
         
        
        
        
      
        
        
        trait HasNumber
        
        
        
      
        
        
        {
        
        
        
      
        
        
            public function number(): string
        
        
        
      
        
        
            {
        
        
        
      
        
        
                return sprintf('INV-%05d', $this->id);
        
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      
        
        
         
        
        
        
      
        
        
        final readonly class Money
        
        
        
      
        
        
        {
        
        
        
      
        
        
            public function __construct(public int $cents) {}
        
        
        
      
        
        
         
        
        
        
      
        
        
            public function add(Money $other): Money
        
        
        
      
        
        
            {
        
        
        
      
        
        
                return new Money($this->cents + $other->cents);
        
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      
        
        
         
        
        
        
      
        
        
        #[Monitored]
        
        
        
      
        
        
        class Invoice
        
        
        
      
        
        
        {
        
        
        
      
        
        
            use HasNumber;
        
        
        
      
        
        
         
        
        
        
      
        
        
            public static int $issued = 0;
        
        
        
      
        
        
         
        
        
        
      
        
        
            #[Auditable]
        
        
        
      
        
        
            public string $customerEmail = '';
        
        
        
      
        
        
         
        
        
        
      
        
        
            public private(set) Status $status = Status::Draft;
        
        
        
      
        
        
         
        
        
        
      
        
        
            protected string $notes = '';
        
        
        
      
        
        
         
        
        
        
      
        
        
            final public string $currency = 'EUR';
        
        
        
      
        
        
         
        
        
        
      
        
        
            public function __construct(public readonly int $id, private Money $total) {}
        
        
        
      
        
        
         
        
        
        
      
        
        
            public static function issue(int $id, Money $total): static
        
        
        
      
        
        
            {
        
        
        
      
        
        
                self::$issued++;
        
        
        
      
        
        
                return new static($id, $total);
        
        
        
      
        
        
            }
        
        
        
      
        
        
         
        
        
        
      
        
        
            public function pay(): void
        
        method
        
      
        
        
            {
        
        
        
      
        
        
                $this->status = Status::Paid;
        
        
        
      
        
        
                $this->audit('paid');
        
        
        
      
        
        
            }
        
        
        
      
        
        
         
        
        
        
      
        
        
            #[Auditable]
        
        
        
      
        
        
            public function refund(int $cents, string $reason): void
        
        
        
      
        
        
            {
        
        
        
      
        
        
                $this->total = $this->recalculate(new Money(-$cents));
        
        
        
      
        
        
                file_put_contents('refunds.log', "{$this->id}: {$reason}\n", FILE_APPEND);
        
        
        
      
        
        
            }
        
        
        
      
        
        
         
        
        
        
      
        
        
            final public function total(): Money
        
        
        
      
        
        
            {
        
        
        
      
        
        
                return $this->total;
        
        
        
      
        
        
            }
        
        
        
      
        
        
         
        
        
        
      
        
        
            protected function audit(string $event): void
        
        
        
      
        
        
            {
        
        
        
      
        
        
                $this->notes .= $event . "\n";
        
        
        
      
        
        
            }
        
        
        
      
        
        
         
        
        
        
      
        
        
            private function recalculate(Money $change): Money
        
        
        
      
        
        
            {
        
        
        
      
        
        
                return $this->total->add($change);
        
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      
Playground

Escribe tu propio pointcut

Escribe un pointcut, edita el PHP y mira qué métodos, propiedades y llamadas selecciona, línea a línea.

Prueba tu pointcut