RFC - 6.0 - Attribute-Based Event Listeners

[josbeir]

Summary

Introduce first-class PHP attributes for registering event listeners in CakePHP 6.x, using the AttributeResolver system for discovery.

The feature is additive and keeps full compatibility with existing event registration patterns:

• EventManager::on() callbacks
• EventListenerInterface::implementedEvents() subscribers
• application/plugin events() hooks

This RFC targets feature parity with the current event system and provides a modern, declarative API that reduces boilerplate.

Motivation

CakePHP already has a robust event system, but listener registration is currently imperative or array-based. Attribute-based registration offers:

• Better locality: event metadata lives next to handler methods.
• Lower boilerplate for common listener declarations.
• Better static discoverability with runtime cache support via AttributeResolver.
• A migration path familiar to developers from frameworks with attribute-driven listener registration.

Goals

• Provide attribute-based listener registration with parity to existing listener capabilities.
• Reuse AttributeResolver for discovery, filtering, and caching.
• Keep behavior deterministic and aligned with EventManager semantics.
• Keep the feature additive with no deprecations in 6.x.

Non-Goals

• Replacing implementedEvents() in 6.x.
• Removing or deprecating imperative on() registration.
• Introducing a new event dispatcher abstraction.

Current System (Baseline)

Existing behavior and extension points:

• Listener registration and dispatch ordering are implemented in src/Event/EventManager.php.
• Subscriber array contract is defined in src/Event/EventListenerInterface.php.
• HTTP lifecycle registration path calls events() then pluginEvents() in src/Http/BaseApplication.php.
• CLI lifecycle registration path calls events() and pluginEvents() in src/Console/CommandRunner.php.
• Attribute discovery and caching primitives are provided by src/AttributeResolver/AttributeResolver.php

Proposed API

Listener Attribute

Add a new attribute class, for example Cake\Event\Attribute\EventListener, applicable to both methods and classes, and repeatable.

Proposed constructor shape:

public function __construct(
    string $event,
    int $priority = EventManager::$defaultPriority,
    ?string $method = null,
) {}

Semantics:

• event: event name string (same event keys used by EventManager::on()), commonly a literal (for example 'foo') or a ::NAME constant.
• priority: ordering parity with existing priority behavior.
• method: optional explicit method name.

Repeatable attributes enable:

• one method to listen to multiple events.
• one class to declare multiple listeners.

Method resolution rules:

1. If method is provided, use it.
2. For method-level attributes without method, use the declaring method.
3. For class-level attributes without method:
   • use __invoke() if present.
   • otherwise, infer method names (on + normalized event identifier), for example foo => onFoo.
4. If no resolvable method exists, treat the declaration as invalid and apply configured error handling.

Usage Examples

use Cake\Event\Attribute\EventListener;
use Cake\Event\EventInterface;

final class OrdersListener
{
    #[EventListener('Order.afterPlace')]
    public function sendReceipt(EventInterface $event): void
    {
    }

    #[EventListener('Order.afterPlace', priority: 5)]
    #[EventListener('Order.afterCancel', priority: 20)]
    public function updateMetrics(EventInterface $event): void
    {
    }
}

use App\Event\CustomEvent;
use Cake\Event\Attribute\EventListener;
use Cake\Event\EventInterface;

#[EventListener(event: CustomEvent::NAME, method: 'onCustomEvent')]
#[EventListener(event: 'foo', priority: 42)]
#[EventListener(event: 'bar', method: 'onBarEvent')]
final class MyMultiListener
{
    public function onCustomEvent(EventInterface $event): void
    {
    }

    public function onFoo(): void
    {
    }

    public function onBarEvent(): void
    {
    }
}

use Cake\Event\Attribute\EventListener;
use Cake\Event\EventInterface;

#[EventListener('Order.afterPlace')]
final class InvokableOrderListener
{
    public function __invoke(EventInterface $event): void
    {
    }
}

Discovery and Registration Model

Discovery Source

Use an appropriate AttributeResolver collection/configuration to query targets decorated with EventListener.

Examples include a dedicated events config or a shared dafaullt config that contains both routing and event metadata.

Expected filtering chain:

1. withAttribute(EventListener::class)
2. withTargetType(AttributeTargetType::METHOD) and withTargetType(AttributeTargetType::CLASS_TYPE)
3. optional namespace/class/plugin constraints by configuration

Registration Lifecycle

Listeners are attached through the existing application event bootstrap hooks:

• HTTP: src/Http/BaseApplication.php
• CLI: src/Console/CommandRunner.php

This keeps behavior explicit and consistent with current docs guidance for registering app/plugin events.

Cache and Performance

Use a resolver configuration strategy with constrained scan paths. This may be a dedicated events config, or a shared config (for example core) used for multiple framework attribute domains such as routing and events:

Parity and Compatibility

Capability Parity

The attribute system must support parity with current event registration patterns:

• Event name mapping (string keys).
• Listener priority.
• Multiple listeners per class/method via repeatable attribute.
• Class-level listeners with __invoke() support.
• Dispatch behavior and stop propagation remain unchanged because dispatch continues through EventManager.

Coexistence Rules

In 6.x, attributes coexist with implementedEvents() and manual on() registration.

• No deprecations are introduced in this RFC.
• Existing listener declarations remain fully supported.
• If the same callable is registered multiple times for the same event and priority via mixed mechanisms, registration should deduplicate by callable identity where feasible.

Ordering Guarantees

• Primary sort remains event priority, identical to current EventManager behavior.
• For equal priority, preserve deterministic discovery/registration order (file and method line order) to avoid non-deterministic execution.

Error Handling

Invalid attribute declarations should fail early in development and tests, while avoiding hard failures in production if configured.

Proposed behavior:

• Debug/test mode: throw clear exceptions for invalid signatures or unresolved methods.
• Production mode: log warning and skip invalid listener declaration.

[queentizy]

hey can i work on this

[jamisonbryant]

@queentizy Thank you for your interest. RFCs are requests for comment and discussion, not assignments for implementation work. The most valuable thing you can do here is read through the proposal, share your perspective on the design, raise concerns, or even suggest alternatives based on your own experience.

If this RFC eventually moves to an implementation phase, we'll open dedicated tracking issues for that work. Community contributors with established context in the discussion will naturally be well-positioned for that.