Skip to content

6.x: Document attribute-based event listeners - #8345

Open
josbeir wants to merge 1 commit into
6.xfrom
docs-event-listener-attributes
Open

josbeir wants to merge 1 commit into
6.xfrom
docs-event-listener-attributes

Conversation

@josbeir

@josbeir josbeir commented Oct 3, 2026

Copy link
Copy Markdown
Contributor

Documents the attribute-based event listeners introduced in cakephp/cakephp#19469 for CakePHP 6.0.

The Events guide now covers method- and class-level attributes, repeatable subscriptions, callable resolution, priorities, discovery and registration, constructor dependency injection, named event managers, and registration errors and deduplication. Listener registration is organized into listener classes, attribute-based listeners, and anonymous listeners. The Attribute Resolver and 6.0 migration guides link to the new section.

Validation:

  • Documentation build, Markdown lint, spelling, internal links, and whitespace checks passed.
  • All nine new PHP snippets passed syntax checks and executed in three isolated runtime scenarios, with 19 checks covering discovery, registration, application bootstrap, dependency injection, and named-manager dispatch.
  • The feature PR's test suite passed: 24 tests, 40 assertions.
  • Generated HTML headings and cross-links were checked; visual browser preview was unavailable.

@markstory markstory added this to the 6.x milestone Oct 4, 2026
Comment on lines +567 to +572
Any feature that needs to discover PHP attributes at runtime can use
`AttributeResolver`. For event subscriptions, use CakePHP's built-in
[`#[EventListener]` attribute and registration APIs](events#registering-listeners-with-attributes).
The example below illustrates how to build a custom integration instead: it
finds methods tagged with a hypothetical `#[ListensTo]` attribute and registers
them as event listeners:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this example be changed now? With EventListener I would hope developers don't do this anymore. Perhaps the example could use TracingSpan as the hypothetical example?


#### Multiple Events and Priorities

The attribute is repeatable, so a method or class can subscribe to multiple

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The attribute is repeatable, so a method or class can subscribe to multiple
The `EventListener` attribute is repeatable, so a method or class can subscribe to multiple

Comment on lines +629 to +630
`EventManagerInterface` also raises this exception, including the attribute's
source location. Abstract classes, interfaces, and traits are skipped.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be clarify that while abstract classes/interfaces/traits are skipped the implementations will not be skipped?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants