From aa2690c76783cc8d7e693402f0fa1b886d3c9f77 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20Menrath?=
 <99024746+Menrath@users.noreply.github.com>
Date: Tue, 18 Nov 2025 09:27:07 +0100
Subject: [PATCH 1/2] Document differences between Events and Hooks APIs

based on https://docs.moodle.org/dev/Hooks_spec#Comparison_with_Moodle_Events
---
 versioned_docs/version-5.1/apis/core/hooks/index.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/versioned_docs/version-5.1/apis/core/hooks/index.md b/versioned_docs/version-5.1/apis/core/hooks/index.md
index 5ba19e46e..449d93379 100644
--- a/versioned_docs/version-5.1/apis/core/hooks/index.md
+++ b/versioned_docs/version-5.1/apis/core/hooks/index.md
@@ -38,6 +38,17 @@ New hooks added to Moodle from Moodle 4.4 onwards must meet the following rules:
 
 ## General concepts
 
+### Comparison to the Events API
+
+The [Events API](https://docs.moodle.org/dev/Events_API) and the Hooks API share similarities, but they serve distinct purposes and operate differently. Key differences include:
+
+- **Communication Flow**: Events use one-way communication (from one to many), while hooks enable two-way communication (typically many to one).
+- **Data Mutation**: Event data is must not be modified, whereas hook callbacks can modify hook instance data.
+- **Execution Timing**: Events are triggered after actions, whereas hooks can be executed at any useful stage (e.g., pre-action, validation, post-action, etc.).
+- **Structure**: Events follow a fixed structure, but hooks can be arbitrary classes that may extend the base.
+- **DB Transactions**: Database transactions may cause event buffering, but the hook manager does not account for transactions.
+- **Logging**: All events are logged (this is contentious), while hooks are not logged.
+
 ### Mapping to PSR-14
 
 Moodle does not allow camelCase for naming of classes and method and Moodle already has events,

From 8b00fcc6f8544ea18e448c215db7d6fe2d2f56c0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20Menrath?=
 <99024746+Menrath@users.noreply.github.com>
Date: Tue, 18 Nov 2025 12:19:07 +0100
Subject: [PATCH 2/2] fix typo

---
 versioned_docs/version-5.1/apis/core/hooks/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/versioned_docs/version-5.1/apis/core/hooks/index.md b/versioned_docs/version-5.1/apis/core/hooks/index.md
index 449d93379..5d4bad26a 100644
--- a/versioned_docs/version-5.1/apis/core/hooks/index.md
+++ b/versioned_docs/version-5.1/apis/core/hooks/index.md
@@ -43,7 +43,7 @@ New hooks added to Moodle from Moodle 4.4 onwards must meet the following rules:
 The [Events API](https://docs.moodle.org/dev/Events_API) and the Hooks API share similarities, but they serve distinct purposes and operate differently. Key differences include:
 
 - **Communication Flow**: Events use one-way communication (from one to many), while hooks enable two-way communication (typically many to one).
-- **Data Mutation**: Event data is must not be modified, whereas hook callbacks can modify hook instance data.
+- **Data Mutation**: Event data must not be modified, whereas hook callbacks can modify hook instance data.
 - **Execution Timing**: Events are triggered after actions, whereas hooks can be executed at any useful stage (e.g., pre-action, validation, post-action, etc.).
 - **Structure**: Events follow a fixed structure, but hooks can be arbitrary classes that may extend the base.
 - **DB Transactions**: Database transactions may cause event buffering, but the hook manager does not account for transactions.