docs(dev/events): modernize / expand event system docs#13957
Open
joshtrichards wants to merge 13 commits intomasterfrom
Open
docs(dev/events): modernize / expand event system docs#13957joshtrichards wants to merge 13 commits intomasterfrom
joshtrichards wants to merge 13 commits intomasterfrom
Conversation
…examples, clarify listener lifecycle Expanded the events documentation w/ detailed explanations, examples, and deprecated hooks and emitters sections. Signed-off-by: Josh <josh.t.richards@gmail.com>
Signed-off-by: Josh <josh.t.richards@gmail.com>
Signed-off-by: Josh <josh.t.richards@gmail.com>
joshtrichards
changed the title
come-nc
requested changes
Jan 6, 2026
Signed-off-by: Josh <josh.t.richards@gmail.com>
Signed-off-by: Josh <josh.t.richards@gmail.com>
Signed-off-by: Josh <josh.t.richards@gmail.com>
…nstantiation Signed-off-by: Josh <josh.t.richards@gmail.com>
Signed-off-by: Josh <josh.t.richards@gmail.com>
Signed-off-by: Josh <josh.t.richards@gmail.com>
Signed-off-by: Josh <josh.t.richards@gmail.com>
Signed-off-by: Josh <josh.t.richards@gmail.com>
Also added new subsections for stopping, blocking, and broadcasting. And updated deprecated section: added GenericEvent and re-organized. Signed-off-by: Josh <josh.t.richards@gmail.com>
Member
Author
|
Revised further:
|
Signed-off-by: Josh Richards <josh.t.richards@gmail.com>
come-nc
reviewed
Mar 23, 2026
| .. tip:: | ||
| Don't get too hung up regarding data transportation at the moment if you're unfamiliar with | ||
| the topic. We'll return to the ``UserCreatedEvent`` and DTO in the context of a fuller example | ||
| later on. For now, let's return to the simpler ``AddEvent``, which merely fires ("this happened"), |
Contributor
There was a problem hiding this comment.
You renamed AddEvent as SomethingHappenedEvent but you still refer to AddEvent here (and maybe in other places, did not check)
come-nc
reviewed
Mar 23, 2026
Comment on lines
+132
to
+135
| .. note:: | ||
| The base ``Event`` class has an empty constructor that was added as a compatibility shim. | ||
| Calling ``parent::__construct()`` is safe and many core event classes still do so by convention, | ||
| but it is not strictly required. Omitting or including it will not affect behavior. |
Contributor
There was a problem hiding this comment.
I would remove this note, it looks more confusing that anything else.
Calling parent::__construct is always safe and recommended, people can read Event code and see that the constructor is empty and not call it if they want.
come-nc
reviewed
Mar 23, 2026
Comment on lines
+159
to
+175
| class AddTwoListener implements IEventListener { | ||
|
|
||
| // The logic triggered in response to an event | ||
| public function handle(Event $event): void { | ||
| if (!($event instanceof AddEvent)) { | ||
| return; | ||
| } | ||
|
|
||
| $event->addToCounter(2); | ||
| } | ||
| } | ||
|
|
||
| The listener is registered during app bootstrap and is lazily instantiated by the upstream DI container the first time the corresponding event fires. During the listener's existence, the handler (``handle()``) within it is called whenever an ``AddEvent`` is fired. The listener's handler implements the business logic (i.e. does the | ||
| interesting thing). If the event fires again within the same request, the same listener instance is reused. | ||
|
|
||
| .. note:: | ||
| PHP parameter type hints cannot be more specific than those on the interface, so you can't type-hint ``AddEvent`` in the method signature; instead use instanceof inside the handler method. |
Contributor
There was a problem hiding this comment.
More AddEvent references here. I would rename the example back to AddEvent at the beginning.
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
6 participants
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