From 401a2af134f54206d2113d2dd05d56069f100c16 Mon Sep 17 00:00:00 2001
From: Kevin Pfeifer <kevin.pfeifer@sunlime.at>
Date: Tue, 21 Oct 2025 15:20:00 +0200
Subject: [PATCH 1/2] add cache events

---
 en/appendices/5-3-migration-guide.rst |  1 +
 en/core-libraries/caching.rst         | 40 +++++++++++++++++++++++++++
 2 files changed, 41 insertions(+)

diff --git a/en/appendices/5-3-migration-guide.rst b/en/appendices/5-3-migration-guide.rst
index 183bc3d909..337eabdace 100644
--- a/en/appendices/5-3-migration-guide.rst
+++ b/en/appendices/5-3-migration-guide.rst
@@ -77,6 +77,7 @@ Cache
 
 - Added Redis Cluster support to ``RedisEngine``. Configure the ``cluster`` option
   with an array of server addresses to enable cluster mode.
+- Several :ref:`cache-events` were added to allow monitoring the caching behavior.
 
 Command
 -------
diff --git a/en/core-libraries/caching.rst b/en/core-libraries/caching.rst
index ae6e2cd4d7..0646135b92 100644
--- a/en/core-libraries/caching.rst
+++ b/en/core-libraries/caching.rst
@@ -673,6 +673,46 @@ The required API for a CacheEngine is
 
     Increment a number under the key and return incremented value
 
+.. _cache-events:
+
+Cache Events
+============
+
+.. versionadded:: 5.3.0
+
+You can add event listeners to the following events:
+
+* ``\Cake\Cache\Event\CacheBeforeGetEvent``
+* ``\Cake\Cache\Event\CacheAfterGetEvent``
+* ``\Cake\Cache\Event\CacheBeforeSetEvent``
+* ``\Cake\Cache\Event\CacheAfterSetEvent``
+* ``\Cake\Cache\Event\CacheBeforeAddEvent``
+* ``\Cake\Cache\Event\CacheAfterAddEvent``
+* ``\Cake\Cache\Event\CacheBeforeDecrementEvent``
+* ``\Cake\Cache\Event\CacheAfterDecrementEvent``
+* ``\Cake\Cache\Event\CacheBeforeDeleteEvent``
+* ``\Cake\Cache\Event\CacheAfterDeleteEvent``
+* ``\Cake\Cache\Event\CacheBeforeIncrementEvent``
+* ``\Cake\Cache\Event\CacheAfterIncrementEvent``
+* ``\Cake\Cache\Event\CacheClearedEvent``
+* ``\Cake\Cache\Event\CacheGroupClearEvent``
+
+an example listener in your ``src/Application.php`` or plugin class would be::
+
+    public function events(EventManagerInterface $eventManager): EventManagerInterface
+    {
+        $eventManager->on(CacheAfterGetEvent::NAME, function (CacheAfterGetEvent $event): void {
+            $key = $event->getKey();
+            $value = $event->getValue();
+            $success = $event->getResult();
+        });
+
+        return $eventManager;
+    }
+
+Different events have different context, so please check the methods inside the custom event class
+if you are looking for certain data.
+
 .. meta::
     :title lang=en: Caching
     :keywords lang=en: uniform api,cache engine,cache system,atomic operations,php class,disk storage,static methods,php extension,consistent manner,similar features,apcu,apc,memcache,queries,cakephp,elements,servers,memory

From b6808e6a4b5dfb231cead286e64f3ab65648bd24 Mon Sep 17 00:00:00 2001
From: Kevin Pfeifer <kevin.pfeifer@sunlime.at>
Date: Tue, 21 Oct 2025 15:34:01 +0200
Subject: [PATCH 2/2] fix build

---
 en/console-commands/commands.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/en/console-commands/commands.rst b/en/console-commands/commands.rst
index 07a30ca735..d45b3289a2 100644
--- a/en/console-commands/commands.rst
+++ b/en/console-commands/commands.rst
@@ -294,7 +294,7 @@ Grouping Commands
 
 By default in the help output CakePHP will group commands into core, app, and
 plugin groups. You can customize the grouping of commands by implementing
-``getGroup()``:
+``getGroup()``::
 
     class CleanupCommand extends Command
     {