Improved EventManager code

Author: Geolim4

CHANGELOG.md

@@ -1,5 +1,5 @@
 ## 9.0.0
-##### 1 november 2021
+##### 1 october 2021
 - __Migration guide__
   - Read the [migration guide](./docs/migration/MigratingFromV8ToV9.md) to upgrade from V8 to V9
 - __API__
@@ -9,6 +9,8 @@
   - Renamed `Api::getPhpFastCacheGitHeadHash()` to `Api::getPhpfastcacheGitHeadHash()`
 - __Cluster__
   - Renamed `\Phpfastcache\Cluster\AggregatorInterface::aggregateNewDriver()` to `\Phpfastcache\Cluster\AggregatorInterface::aggregateDriverByName()` 
+- __Exceptions__
+  - Added `PhpfastcacheEventManagerException` for EventManager-related exceptions
 - __Global__
   - Removed magics methods from CacheManager `CacheManager::DriverName()`, use `CacheManager::getInstance('DriverName')` instead
   - Slightly increased performances on some critical points of the library
@@ -45,7 +47,9 @@
   - Added `Devrandom` with configurable factor chance and data length
   - Renamed classes `\Phpfastcache\Cluster\Drivers\[STATEGY]\[CLUSTER_NAME]Cluster` to `\Phpfastcache\Cluster\Drivers\[STATEGY]\Driver` for better driver naming across the project
 - __Events__
-  - Added `\Phpfastcache\Event\EventReferenceParameter` class, see [EVENTS.md](./docs/EVENTS.md) file for more information
+  - Added `\Phpfastcache\Event\EventReferenceParameter` class and more events such as driver-specific events, see [EVENTS.md](./docs/EVENTS.md) file for more information
+  - Event callbacks will now receive the `eventName` as an extra _last_ callback parameter (except for `onEveryEvents` callbacks)
+  - Added `EventManagerInterface::on(array $eventNames, $callback)` method, to subscribe to multiple events in once with the same callback
   - Added method named `unbindAllEventCallbacks(): bool` to `EventManagerInterface` to allow you to unbind/clear all event from an event instance
   - Updated argument type #2 (`$items`) of `onCacheSaveMultipleItems()` event from `ExtendedCacheItemInterface[]` to `EventReferenceParameter($items)`
   - Updated argument type #2 (`$items`) of `onCacheCommitItem()` event from `ExtendedCacheItemInterface[]` to `EventReferenceParameter($items)`

docs/EVENTS.md

@@ -34,13 +34,31 @@ EventManager::getInstance()->unbindEventCallback('onCacheGetItem', 'myCallbackNa
 
 ```
 
-:new: In V9 some callback parameter, that aren't objects, are passed by reference via the new `\Phpfastcache\Event\EventReferenceParameter` class.\
-This class is instantiated and passed to the callback with the original value passed **by reference** allowing you to either read or re-write its value.\
-If it's allowed by the event dispatcher the type can be changed or not.\
-If you try to while it's not allowed, you will get a `PhpfastcacheInvalidArgumentException` when trying to call `\Phpfastcache\Event\EventReferenceParameter::setParameterValue()`\
-Finally the class `\Phpfastcache\Event\EventReferenceParameter` is `invokable` and trying to do so will return you the parameter value.\
+:new: in V8
 
-:new: In V9, a method named `unbindAllEventCallbacks(): bool` has been added to `EventManagerInterface` to allow you to unbind/clear all event from an event instance.
+You can simply subscribe to **every** events at once of Phpfastcache.
+```php
+<?php
+use Phpfastcache\EventManager;
+
+EventManager::getInstance()->onEveryEvents(static function (string $eventName, ...$args) {
+    echo sprintf("Triggered event '{$eventName}' with %d arguments provided", count($args));
+}, 'debugCallback');
+```
+
+This is an exhaustive list, and it will be updated as soon as new events will be added to the Core.
+
+
+:new: In V9
+
+- Some callback parameter, that are __NOT__ objects, are passed by reference via the new `\Phpfastcache\Event\EventReferenceParameter` class.\
+  This class is instantiated and passed to the callback with the original value passed **by reference** allowing you to either read or re-write its value.\
+  If it's allowed by the event dispatcher the type can be changed or not.\
+  If you try to while it's not allowed, you will get a `PhpfastcacheInvalidArgumentException` when trying to call `\Phpfastcache\Event\EventReferenceParameter::setParameterValue()`\
+  Finally the class `\Phpfastcache\Event\EventReferenceParameter` is `invokable` and trying to do so will return you the parameter value.\
+- A method named `unbindAllEventCallbacks(): bool` has been added to `EventManagerInterface` to allow you to unbind/clear all event from an event instance.
+- Event callbacks will now receive the `eventName` as an extra _last_ callback parameter (except for `onEveryEvents` callbacks)
+- Added `EventManagerInterface::on(array $eventNames, $callback)` method, to subscribe to multiple events in once with the same callback
 
 ## List of active events:
 ### ItemPool Events
@@ -226,14 +244,35 @@ Finally the class `\Phpfastcache\Event\EventReferenceParameter` is `invokable` a
     - **Risky Circular Methods**
         - *ExtendedCacheItemInterface::expiresAt()*
 
-:new: As of the **V8** you can simply subscribe to **every** events at once of Phpfastcache.
-```php
-<?php
-use Phpfastcache\EventManager;
+### Driver-specific Events (as of V9)
+#### Arangodb
+- onArangodbConnection(*Callable* **$callback**)
+    - **Callback arguments**
+        - *ExtendedCacheItemPoolInterface* **$itemPool**
+        - *EventReferenceParameter($connectionOptions)* **$connectionOptions** _via EventReferenceParameter object_ **(type modification forbidden)**
+    - **Scope**
+        - Arangodb Driver
+    - **Description**
+        - Allow you to alter the parameters built used to connect to Arangodb server
+    - **Risky Circular Methods**: None
 
-EventManager::getInstance()->onEveryEvents(static function (string $eventName, ...$args) {
-    echo sprintf("Triggered event '{$eventName}' with %d arguments provided", count($args));
-}, 'debugCallback');
-```
+- onArangodbCollectionParams(*Callable* **$callback**)
+    - **Callback arguments**
+        - *ExtendedCacheItemPoolInterface* **$itemPool**
+        - *EventReferenceParameter($params)* **$params** _via EventReferenceParameter object_ **(type modification forbidden)**
+    - **Scope**
+        - Arangodb Driver
+    - **Description**
+        - Allow you to alter the parameters built used to create the collection
+    - **Risky Circular Methods**: None
 
-This is an exhaustive list and it will be updated as soon as new events will be added to the Core.
+#### Dynamodb
+- onDynamodbCreateTable(*Callable* **$callback**)
+    - **Callback arguments**
+        - *ExtendedCacheItemPoolInterface* **$itemPool**
+        - *EventReferenceParameter($params)* **$params** _via EventReferenceParameter object_ **(type modification forbidden)**
+    - **Scope**
+        - Dynamodb Driver
+    - **Description**
+        - Allow you to alter the parameters built used to create the table
+    - **Risky Circular Methods**: None

lib/Phpfastcache/CacheManager.php

@@ -108,8 +108,11 @@ public static function getInstance(string $driver, ?ConfigurationOptionInterface
                 if ($configClass !== $config::class) {
                     $config = new $configClass($config->toArray());
                 }
-                self::$instances[$instanceId] = new $driverClass($config, $instanceId);
-                self::$instances[$instanceId]->setEventManager(EventManager::getInstance());
+                self::$instances[$instanceId] = new $driverClass(
+                    $config,
+                    $instanceId,
+                    EventManager::getInstance()
+                );
             } else {
                 throw new PhpfastcacheDriverNotFoundException(sprintf('The driver "%s" does not exists', $driver));
             }

lib/Phpfastcache/Cluster/ClusterAggregator.php

@@ -18,6 +18,7 @@
 use Exception;
 use Phpfastcache\CacheManager;
 use Phpfastcache\Config\ConfigurationOption;
+use Phpfastcache\EventManager;
 use Phpfastcache\Exceptions\PhpfastcacheDriverCheckException;
 use Phpfastcache\Exceptions\PhpfastcacheDriverException;
 use Phpfastcache\Exceptions\PhpfastcacheDriverNotFoundException;
@@ -144,6 +145,7 @@ public function getCluster(int $strategy = AggregatorInterface::STRATEGY_FULL_RE
                 $clusterClass = ClusterPoolAbstract::STRATEGY[$strategy];
                 $this->cluster = new $clusterClass(
                     $this->getClusterAggregatorName(),
+                    EventManager::getInstance(),
                     ...\array_values($this->driverPools)
                 );
 

lib/Phpfastcache/Cluster/ClusterPoolAbstract.php

@@ -25,6 +25,7 @@
 use Phpfastcache\Core\Pool\TaggableCacheItemPoolTrait;
 use Phpfastcache\Entities\DriverIO;
 use Phpfastcache\Entities\DriverStatistic;
+use Phpfastcache\Event\EventManagerInterface;
 use Phpfastcache\EventManager;
 use Phpfastcache\Exceptions\PhpfastcacheCoreException;
 use Phpfastcache\Exceptions\PhpfastcacheDriverCheckException;
@@ -61,6 +62,7 @@ abstract class ClusterPoolAbstract implements ClusterPoolInterface
     /**
      * ClusterPoolAbstract constructor.
      * @param string $clusterName
+     * @param EventManagerInterface $em
      * @param ExtendedCacheItemPoolInterface ...$driverPools
      * @throws PhpfastcacheDriverCheckException
      * @throws PhpfastcacheDriverConnectException
@@ -69,13 +71,13 @@ abstract class ClusterPoolAbstract implements ClusterPoolInterface
      * @throws PhpfastcacheDriverException
      * @throws PhpfastcacheIOException
      */
-    public function __construct(string $clusterName, ExtendedCacheItemPoolInterface ...$driverPools)
+    public function __construct(string $clusterName, EventManagerInterface $em, ExtendedCacheItemPoolInterface ...$driverPools)
     {
         if (count($driverPools) < 2) {
             throw new PhpfastcacheInvalidArgumentException('A cluster requires at least two pools to be working.');
         }
         $this->clusterPools = $driverPools;
-        $this->__parentConstruct(new ConfigurationOption(), $clusterName);
+        $this->__parentConstruct(new ConfigurationOption(), $clusterName, $em);
         $this->setEventManager(EventManager::getInstance());
     }
 
@@ -183,7 +185,7 @@ protected function getStandardizedItem(ExtendedCacheItemInterface $item, Extende
             if ($driverPool === $this) {
                 /** @var ExtendedCacheItemInterface $itemPool */
                 $itemClass = $driverPool->getItemClass();
-                $itemPool = new $itemClass($this, $item->getKey());
+                $itemPool = new $itemClass($this, $item->getKey(), $this->getEventManager());
 
                 $this->remapCacheItem($item, $itemPool, $driverPool);
 

lib/Phpfastcache/Cluster/Drivers/FullReplication/Driver.php

@@ -72,7 +72,7 @@ public function getItem(string $key): ExtendedCacheItemInterface
             }
         }
 
-        return $this->getStandardizedItem($item ?? new Item($this, $key), $this);
+        return $this->getStandardizedItem($item ?? new Item($this, $key, $this->getEventManager()), $this);
     }
 
     /**

lib/Phpfastcache/Cluster/Drivers/MasterSlaveReplication/Driver.php

@@ -18,11 +18,15 @@
 use Phpfastcache\Cluster\ClusterPoolAbstract;
 use Phpfastcache\Core\Item\ExtendedCacheItemInterface;
 use Phpfastcache\Core\Pool\ExtendedCacheItemPoolInterface;
+use Phpfastcache\EventManager;
+use Phpfastcache\Exceptions\PhpfastcacheCoreException;
 use Phpfastcache\Exceptions\PhpfastcacheDriverCheckException;
 use Phpfastcache\Exceptions\PhpfastcacheDriverConnectException;
+use Phpfastcache\Exceptions\PhpfastcacheDriverException;
 use Phpfastcache\Exceptions\PhpfastcacheExceptionInterface;
 use Phpfastcache\Exceptions\PhpfastcacheInvalidArgumentException;
 use Phpfastcache\Exceptions\PhpfastcacheInvalidConfigurationException;
+use Phpfastcache\Exceptions\PhpfastcacheIOException;
 use Phpfastcache\Exceptions\PhpfastcacheReplicationException;
 use Psr\Cache\CacheItemInterface;
 use ReflectionException;
@@ -32,20 +36,22 @@ class Driver extends ClusterPoolAbstract
     /**
      * MasterSlaveReplicationCluster constructor.
      * @param string $clusterName
+     * @param EventManager $em
      * @param ExtendedCacheItemPoolInterface ...$driverPools
-     * @throws PhpfastcacheInvalidArgumentException
      * @throws PhpfastcacheDriverCheckException
      * @throws PhpfastcacheDriverConnectException
-     * @throws PhpfastcacheInvalidConfigurationException
-     * @throws ReflectionException
+     * @throws PhpfastcacheInvalidArgumentException
+     * @throws PhpfastcacheCoreException
+     * @throws PhpfastcacheDriverException
+     * @throws PhpfastcacheIOException
      */
-    public function __construct(string $clusterName, ExtendedCacheItemPoolInterface ...$driverPools)
+    public function __construct(string $clusterName, EventManager $em, ExtendedCacheItemPoolInterface ...$driverPools)
     {
         if (\count($driverPools) !== 2) {
             throw new PhpfastcacheInvalidArgumentException('A "master/slave" cluster requires exactly two pools to be working.');
         }
 
-        parent::__construct($clusterName, ...$driverPools);
+        parent::__construct($clusterName, $em, ...$driverPools);
     }
 
     /**
@@ -54,7 +60,7 @@ public function __construct(string $clusterName, ExtendedCacheItemPoolInterface
     public function getItem(string $key): ExtendedCacheItemInterface
     {
         return $this->getStandardizedItem(
-            $this->makeOperation(static fn (ExtendedCacheItemPoolInterface $pool) => $pool->getItem($key)) ?? new Item($this, $key),
+            $this->makeOperation(static fn (ExtendedCacheItemPoolInterface $pool) => $pool->getItem($key)) ?? new Item($this, $key, $this->getEventManager()),
             $this
         );
     }

lib/Phpfastcache/Cluster/Drivers/RandomReplication/Driver.php

@@ -17,6 +17,7 @@
 
 use Phpfastcache\Cluster\Drivers\MasterSlaveReplication\Driver as MasterSlaveReplicationDriver;
 use Phpfastcache\Core\Pool\ExtendedCacheItemPoolInterface;
+use Phpfastcache\Event\EventManagerInterface;
 use ReflectionException;
 use ReflectionMethod;
 
@@ -28,10 +29,10 @@ class Driver extends MasterSlaveReplicationDriver
      * @param ExtendedCacheItemPoolInterface ...$driverPools
      * @throws ReflectionException
      */
-    public function __construct(string $clusterName, ExtendedCacheItemPoolInterface ...$driverPools)
+    public function __construct(string $clusterName, EventManagerInterface $em, ExtendedCacheItemPoolInterface ...$driverPools)
     {
         (new ReflectionMethod(\get_parent_class(\get_parent_class($this)), __FUNCTION__))
-            ->invoke($this, $clusterName, ...$driverPools);
+            ->invoke($this, $clusterName, $em, ...$driverPools);
         $randomPool = $driverPools[\random_int(0, \count($driverPools) - 1)];
 
         $this->eventManager->dispatch(

lib/Phpfastcache/Cluster/Drivers/SemiReplication/Driver.php

@@ -51,7 +51,7 @@ public function getItem(string $key): ExtendedCacheItemInterface
             throw new PhpfastcacheReplicationException('Every pools thrown an exception');
         }
 
-        return $this->getStandardizedItem($item ?? new Item($this, $key), $this);
+        return $this->getStandardizedItem($item ?? new Item($this, $key, $this->getEventManager()), $this);
     }
 
     /**

lib/Phpfastcache/Core/Item/ExtendedCacheItemTrait.php

@@ -18,6 +18,7 @@
 use DateTime;
 use DateTimeInterface;
 use Phpfastcache\Core\Pool\ExtendedCacheItemPoolInterface;
+use Phpfastcache\Event\EventManagerInterface;
 use Phpfastcache\Exceptions\PhpfastcacheInvalidArgumentException;
 use Phpfastcache\Exceptions\PhpfastcacheLogicException;
 use Phpfastcache\Util\ClassNamespaceResolverTrait;
@@ -34,12 +35,14 @@ trait ExtendedCacheItemTrait
      * Item constructor.
      * @param ExtendedCacheItemPoolInterface $driver
      * @param string $key
+     * @param EventManagerInterface $em
      * @throws PhpfastcacheInvalidArgumentException
      */
-    public function __construct(ExtendedCacheItemPoolInterface $driver, string $key)
+    public function __construct(ExtendedCacheItemPoolInterface $driver, string $key, EventManagerInterface $em)
     {
         $this->data = null;
         $this->key = $key;
+        $this->setEventManager($em);
         $this->setDriver($driver);
         if ($driver->getConfig()->isUseStaticItemCaching()) {
             $this->driver->setItem($this);

lib/Phpfastcache/Core/Pool/CacheItemPoolTrait.php

@@ -34,7 +34,6 @@
 
 trait CacheItemPoolTrait
 {
-    use EventManagerDispatcherTrait;
     use DriverBaseTrait;
 
     /**
@@ -128,8 +127,7 @@ public function getItem(string $key): ExtendedCacheItemInterface
             $cacheSlamsSpendSeconds = 0;
             $itemClass = self::getItemClass();
             /** @var $item ExtendedCacheItemInterface */
-            $item = new $itemClass($this, $key);
-            $item->setEventManager($this->eventManager);
+            $item = new $itemClass($this, $key, $this->eventManager);
 
             getItemDriverRead:
             {
@@ -405,9 +403,9 @@ public function commit(): bool
      * @return bool
      * @throws PhpfastcacheCoreException
      * @throws PhpfastcacheDriverException
+     * @throws PhpfastcacheIOException
      * @throws PhpfastcacheInvalidArgumentException
      * @throws PhpfastcacheLogicException
-     * @throws \ReflectionException
      */
     public function save(CacheItemInterface $item): bool
     {
@@ -438,10 +436,9 @@ public function save(CacheItemInterface $item): bool
             /**
              * @var $itemBatch ExtendedCacheItemInterface
              */
-            $class = new ReflectionClass((new ReflectionObject($this))->getNamespaceName() . '\Item');
-            $itemBatch = $class->newInstanceArgs([$this, $item->getKey()]);
-            $itemBatch->setEventManager($this->eventManager)
-                ->set(new ItemBatch($item->getKey(), new DateTime()))
+            $itemClassName = self::getItemClass();
+            $itemBatch = new $itemClassName($this, $item->getKey(), $this->eventManager);
+            $itemBatch->set(new ItemBatch($item->getKey(), new DateTime()))
                 ->expiresAfter($this->getConfig()->getCacheSlamsTimeout());
 
             /**

lib/Phpfastcache/Core/Pool/DriverBaseTrait.php

@@ -18,6 +18,8 @@
 use DateTime;
 use DateTimeInterface;
 use Phpfastcache\Config\ConfigurationOptionInterface;
+use Phpfastcache\Event\EventManagerDispatcherTrait;
+use Phpfastcache\Event\EventManagerInterface;
 use Phpfastcache\Exceptions\PhpfastcacheInvalidArgumentException;
 use Phpfastcache\Util\ClassNamespaceResolverTrait;
 use Throwable;
@@ -35,6 +37,7 @@ trait DriverBaseTrait
 {
     use DriverPoolAbstractTrait;
     use ClassNamespaceResolverTrait;
+    use EventManagerDispatcherTrait;
 
     protected static array $cacheItemClasses = [];
 
@@ -50,14 +53,16 @@ trait DriverBaseTrait
      * Driver constructor.
      * @param ConfigurationOptionInterface $config
      * @param string $instanceId
+     * @param EventManagerInterface $em
      * @throws PhpfastcacheCoreException
      * @throws PhpfastcacheDriverCheckException
      * @throws PhpfastcacheDriverConnectException
      * @throws PhpfastcacheIOException
      * @throws PhpfastcacheInvalidArgumentException
      */
-    public function __construct(ConfigurationOptionInterface $config, string $instanceId)
+    public function __construct(ConfigurationOptionInterface $config, string $instanceId, EventManagerInterface $em)
     {
+        $this->setEventManager($em);
         $this->setConfig($config);
         $this->instanceId = $instanceId;
         $this->IO = new DriverIO();