[11.x] Add get, write and forget cache events (#51560)

* Add `get`, `write` and `forget` cache events

* formatting

* formatting

* formatting

---------

Co-authored-by: Taylor Otwell <taylor@laravel.com>

Author: stayallive

src/Illuminate/Cache/Events/ForgettingKey.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Illuminate\Cache\Events;
+
+class ForgettingKey extends CacheEvent
+{
+    //
+}

src/Illuminate/Cache/Events/KeyForgetFailed.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Illuminate\Cache\Events;
+
+class KeyForgetFailed extends CacheEvent
+{
+    //
+}

src/Illuminate/Cache/Events/KeyWriteFailed.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace Illuminate\Cache\Events;
+
+class KeyWriteFailed extends CacheEvent
+{
+    /**
+     * The value that would have been written.
+     *
+     * @var mixed
+     */
+    public $value;
+
+    /**
+     * The number of seconds the key should have been valid.
+     *
+     * @var int|null
+     */
+    public $seconds;
+
+    /**
+     * Create a new event instance.
+     *
+     * @param  string|null  $storeName
+     * @param  string  $key
+     * @param  mixed  $value
+     * @param  int|null  $seconds
+     * @param  array  $tags
+     * @return void
+     */
+    public function __construct($storeName, $key, $value, $seconds = null, $tags = [])
+    {
+        parent::__construct($storeName, $key, $tags);
+
+        $this->value = $value;
+        $this->seconds = $seconds;
+    }
+}

src/Illuminate/Cache/Events/RetrievingKey.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Illuminate\Cache\Events;
+
+class RetrievingKey extends CacheEvent
+{
+    //
+}

src/Illuminate/Cache/Events/RetrievingManyKeys.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace Illuminate\Cache\Events;
+
+class RetrievingManyKeys extends CacheEvent
+{
+    /**
+     * The keys that are being retrieved.
+     *
+     * @var array
+     */
+    public $keys;
+
+    /**
+     * Create a new event instance.
+     *
+     * @param  string|null  $storeName
+     * @param  array  $keys
+     * @param  array  $tags
+     * @return void
+     */
+    public function __construct($storeName, $keys, array $tags = [])
+    {
+        parent::__construct($storeName, $keys[0] ?? '', $tags);
+
+        $this->keys = $keys;
+    }
+}

src/Illuminate/Cache/Events/WritingKey.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace Illuminate\Cache\Events;
+
+class WritingKey extends CacheEvent
+{
+    /**
+     * The value that will be written.
+     *
+     * @var mixed
+     */
+    public $value;
+
+    /**
+     * The number of seconds the key should be valid.
+     *
+     * @var int|null
+     */
+    public $seconds;
+
+    /**
+     * Create a new event instance.
+     *
+     * @param  string|null  $storeName
+     * @param  string  $key
+     * @param  mixed  $value
+     * @param  int|null  $seconds
+     * @param  array  $tags
+     * @return void
+     */
+    public function __construct($storeName, $key, $value, $seconds = null, $tags = [])
+    {
+        parent::__construct($storeName, $key, $tags);
+
+        $this->value = $value;
+        $this->seconds = $seconds;
+    }
+}

src/Illuminate/Cache/Events/WritingManyKeys.php

@@ -0,0 +1,46 @@
+<?php
+
+namespace Illuminate\Cache\Events;
+
+class WritingManyKeys extends CacheEvent
+{
+    /**
+     * The keys that are being written.
+     *
+     * @var mixed
+     */
+    public $keys;
+
+    /**
+     * The value that is being written.
+     *
+     * @var mixed
+     */
+    public $values;
+
+    /**
+     * The number of seconds the keys should be valid.
+     *
+     * @var int|null
+     */
+    public $seconds;
+
+    /**
+     * Create a new event instance.
+     *
+     * @param  string|null  $storeName
+     * @param  array  $keys
+     * @param  array  $values
+     * @param  int|null  $seconds
+     * @param  array  $tags
+     * @return void
+     */
+    public function __construct($storeName, $keys, $values, $seconds = null, $tags = [])
+    {
+        parent::__construct($storeName, $keys[0], $tags);
+
+        $this->keys = $keys;
+        $this->values = $values;
+        $this->seconds = $seconds;
+    }
+}

src/Illuminate/Cache/Repository.php

@@ -8,8 +8,15 @@
 use DateTimeInterface;
 use Illuminate\Cache\Events\CacheHit;
 use Illuminate\Cache\Events\CacheMissed;
+use Illuminate\Cache\Events\ForgettingKey;
+use Illuminate\Cache\Events\KeyForgetFailed;
 use Illuminate\Cache\Events\KeyForgotten;
+use Illuminate\Cache\Events\KeyWriteFailed;
 use Illuminate\Cache\Events\KeyWritten;
+use Illuminate\Cache\Events\RetrievingKey;
+use Illuminate\Cache\Events\RetrievingManyKeys;
+use Illuminate\Cache\Events\WritingKey;
+use Illuminate\Cache\Events\WritingManyKeys;
 use Illuminate\Contracts\Cache\Repository as CacheContract;
 use Illuminate\Contracts\Cache\Store;
 use Illuminate\Contracts\Events\Dispatcher;
@@ -104,6 +111,8 @@ public function get($key, $default = null): mixed
             return $this->many($key);
         }
 
+        $this->event(new RetrievingKey($this->getName(), $key));
+
         $value = $this->store->get($this->itemKey($key));
 
         // If we could not find the cache value, we will fire the missed event and get
@@ -130,6 +139,8 @@ public function get($key, $default = null): mixed
      */
     public function many(array $keys)
     {
+        $this->event(new RetrievingManyKeys($this->getName(), $keys));
+
         $values = $this->store->many(collect($keys)->map(function ($value, $key) {
             return is_string($key) ? $key : $value;
         })->values()->all());
@@ -222,10 +233,14 @@ public function put($key, $value, $ttl = null)
             return $this->forget($key);
         }
 
+        $this->event(new WritingKey($this->getName(), $key, $value, $seconds));
+
         $result = $this->store->put($this->itemKey($key), $value, $seconds);
 
         if ($result) {
             $this->event(new KeyWritten($this->getName(), $key, $value, $seconds));
+        } else {
+            $this->event(new KeyWriteFailed($this->getName(), $key, $value, $seconds));
         }
 
         return $result;
@@ -260,11 +275,15 @@ public function putMany(array $values, $ttl = null)
             return $this->deleteMultiple(array_keys($values));
         }
 
+        $this->event(new WritingManyKeys($this->getName(), array_keys($values), array_values($values), $seconds));
+
         $result = $this->store->putMany($values, $seconds);
 
-        if ($result) {
-            foreach ($values as $key => $value) {
+        foreach ($values as $key => $value) {
+            if ($result) {
                 $this->event(new KeyWritten($this->getName(), $key, $value, $seconds));
+            } else {
+                $this->event(new KeyWriteFailed($this->getName(), $key, $value, $seconds));
             }
         }
 
@@ -372,10 +391,14 @@ public function decrement($key, $value = 1)
      */
     public function forever($key, $value)
     {
+        $this->event(new WritingKey($this->getName(), $key, $value));
+
         $result = $this->store->forever($this->itemKey($key), $value);
 
         if ($result) {
             $this->event(new KeyWritten($this->getName(), $key, $value));
+        } else {
+            $this->event(new KeyWriteFailed($this->getName(), $key, $value));
         }
 
         return $result;
@@ -456,9 +479,13 @@ public function rememberForever($key, Closure $callback)
      */
     public function forget($key)
     {
+        $this->event(new ForgettingKey($this->getName(), $key));
+
         return tap($this->store->forget($this->itemKey($key)), function ($result) use ($key) {
             if ($result) {
                 $this->event(new KeyForgotten($this->getName(), $key));
+            } else {
+                $this->event(new KeyForgetFailed($this->getName(), $key));
             }
         });
     }