An amber beam passes through three dark glass walls.
Feature · Intercept anything

No method is off limits.

Intercept what others can't. Public, protected, private, final, static, enum and readonly-class methods. The new engine reaches beyond the limitations of traditional proxy-based interception.

Advice types

Five ways to attach the behavior.

Run logic before, after or around a method call. Handle exceptions, change execution flow or introduce new capabilities — all through declarative behaviors.

#[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

Choose what gets a behavior.

Target methods, properties and attributes with expressive matching rules. See exactly what each rule selects.

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

Write your own pointcut

Type a pointcut, edit the PHP, and see which methods, properties and calls it selects, line by line.

Try your pointcut