docs(dev/events): modernize / expand event system docs #13957
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…examples, clarify listener lifecycle Expanded the events documentation w/ detailed explanations, examples, and deprecated hooks and emitters sections. Signed-off-by: Josh <[email protected]>
Signed-off-by: Josh <[email protected]>
Signed-off-by: Josh <[email protected]>
joshtrichards
changed the title
come-nc
requested changes
Jan 6, 2026
Comment on lines
+143
to
+144
| */ | ||
| class AddTwoListener implements IEventListener { |
Contributor
There was a problem hiding this comment.
Suggested change
| */ | |
| class AddTwoListener implements IEventListener { | |
| * @template-implements IEventListener<AddEvent> | |
| */ | |
| class AddTwoListener implements IEventListener { |
Comment on lines
+163
to
+164
| By default there is no persistent "listener object" kept by the dispatcher. Each time the event is fired, the DI container will lazily instantiate a new instance of the listener (the class), invoke the handle() method, and then discard the instance. There are more advanced approaches to listener registration (singleton/shared), but | ||
| that is a more advanced use case -- not the default for DI-registered event listeners in Nextcloud. You may find this approach in core, but rarely in apps. |
Contributor
There was a problem hiding this comment.
Is that true? I would expect core to use DI to get the listener, so as a singleton by default. Meaning if 2 instance of the same events are fired in the same request the same instance of the listener will be used.
| /** | ||
| * Listener that uses MyService (external dependency) when an AddEvent is fired. | ||
| */ |
Contributor
There was a problem hiding this comment.
template-implements here as well
| /** | ||
| * Listener that logs the creation of a user when UserCreatedEvent is fired. | ||
| */ |
| // Logger is injected by the DI container | ||
| public function __construct( | ||
| private LoggerInterface $logger |
Contributor
There was a problem hiding this comment.
Suggested change
| private LoggerInterface $logger | |
| private LoggerInterface $logger, |
The codestyle currently used forces a comma here.
| // Emit an event so other apps can react | ||
| $event = new UserCreatedEvent($user); | ||
| $this->dispatcher->dispatch($event); |
Contributor
There was a problem hiding this comment.
Suggested change
| $this->dispatcher->dispatch($event); | |
| $this->dispatcher->dispatchTyped($event); |
dispatch is deprecated and has another signature
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
☑️ Resolves
The existing Events chapter was showing its age and in need of a refactor.
It was a bit confusing in some spots, wasn't up-to-date with current best practices, and lacked coverage of the dispatcher.
This PR modernizes and expands the documentation for Nextcloud Events:
These changes ensure app authors have clear, up-to-date, and actionable guidance for both consuming and producing events in Nextcloud apps.
🖼️ Screenshots