Use Phalcon events contracts

Author: jturbide

CHANGELOG.md

@@ -134,6 +134,8 @@ release notes.
 - Normalized mailer driver and SMTP encryption config case-insensitively,
   validated mailer option shapes, and failed fast on unsupported values before
   send-time network behavior.
+- Replaced internal references to deprecated Phalcon events interfaces with
+  their `Phalcon\Contracts\Events` equivalents.
 
 ## 3.0.3 - 2026-06-10
 

src/Bootstrap.php

@@ -14,8 +14,9 @@
 namespace PhalconKit;
 
 use Phalcon\Application\AbstractApplication;
+use Phalcon\Contracts\Events\Manager as EventsManagerContract;
 use Phalcon\Di\Di as PhalconDi;
-use Phalcon\Events;
+use Phalcon\Events\Manager as EventsManager;
 use Phalcon\Http\ResponseInterface;
 use PhalconKit\Config\ConfigInterface;
 use PhalconKit\Cli\Console;
@@ -157,7 +158,7 @@ class Bootstrap
     public function __construct(?string $mode = null)
     {
         $this->setMode($mode);
-        $this->setEventsManager(new Events\Manager());
+        $this->setEventsManager(new EventsManager());
         $this->setDI();
         $this->initialize();
         $this->registerConfig();
@@ -400,7 +401,7 @@ protected function attachConfiguredEventListeners(): void
 
         ConfiguredEventListeners::attach(
             $this->di,
-            $this->di->getTyped('eventsManager', Events\ManagerInterface::class),
+            $this->di->getTyped('eventsManager', EventsManagerContract::class),
             $listeners
         );
         $this->configuredEventListenersAttached = true;

src/Db/Events/Logger.php

@@ -13,8 +13,8 @@
 
 namespace PhalconKit\Db\Events;
 
+use Phalcon\Contracts\Events\Event as EventContract;
 use Phalcon\Db\Adapter\AbstractAdapter;
-use Phalcon\Events\EventInterface;
 use Phalcon\Logger\Exception as LoggerException;
 use PhalconKit\Di\Injectable;
 
@@ -28,12 +28,12 @@ class Logger extends Injectable
     /**
      * Executes before a database query is executed.
      *
-     * @param EventInterface $event The event object.
+     * @param EventContract $event The event object.
      * @param AbstractAdapter $connection The database connection object.
      * @return void
      * @throws LoggerException If Phalcon cannot write the query log entry.
      */
-    public function beforeQuery(EventInterface $event, AbstractAdapter $connection): void
+    public function beforeQuery(EventContract $event, AbstractAdapter $connection): void
     {
         if ($this->config->path('logger.enable') || $this->config->path('app.logger')) {
             if ($this->config->path('loggers.database.enable')) {

src/Db/Events/Profiler.php

@@ -13,8 +13,8 @@
 
 namespace PhalconKit\Db\Events;
 
+use Phalcon\Contracts\Events\Event as EventContract;
 use Phalcon\Db\Adapter\AbstractAdapter;
-use Phalcon\Events\EventInterface;
 use PhalconKit\Di\Injectable;
 
 /**
@@ -47,11 +47,11 @@ public function isEnabled(): bool
      * Stopped events are ignored so listeners earlier in the chain can cancel
      * profiling together with the query.
      *
-     * @param EventInterface $event Database `beforeQuery` event.
+     * @param EventContract $event Database `beforeQuery` event.
      * @param AbstractAdapter $connection Connection that is about to execute
      *     the statement.
      */
-    public function beforeQuery(EventInterface $event, AbstractAdapter $connection): void
+    public function beforeQuery(EventContract $event, AbstractAdapter $connection): void
     {
         if ($this->isEnabled()) {
             if (!$event->isStopped()) {
@@ -69,10 +69,10 @@ public function beforeQuery(EventInterface $event, AbstractAdapter $connection):
      *
      * @scrutinizer ignore-unused
      *
-     * @param EventInterface $event Database `afterQuery` event.
+     * @param EventContract $event Database `afterQuery` event.
      * @param AbstractAdapter $connection Connection that executed the statement.
      */
-    public function afterQuery(EventInterface $event, AbstractAdapter $connection): void
+    public function afterQuery(EventContract $event, AbstractAdapter $connection): void
     {
         if ($this->isEnabled()) {
             $this->profiler->stopProfile();

src/Di/AbstractInjectable.php

@@ -31,7 +31,7 @@
  * @property \Phalcon\Flash\Direct $flash
  * @property \Phalcon\Flash\Session $flashSession
  * @property \Phalcon\Session\ManagerInterface $session
- * @property \Phalcon\Events\Manager|\Phalcon\Events\ManagerInterface $eventsManager
+ * @property \Phalcon\Events\Manager|\Phalcon\Contracts\Events\Manager $eventsManager
  * @property \Phalcon\Db\Adapter\AdapterInterface $db
  * @property \PhalconKit\Encryption\Security|\Phalcon\Encryption\Security $security
  * @property \Phalcon\Encryption\Crypt|\Phalcon\Encryption\Crypt\CryptInterface $crypt

src/Di/InjectableProperties.php

@@ -50,7 +50,7 @@
  * @property \Phalcon\Db\Adapter\AbstractAdapter $db
  * @property \Phalcon\Db\Adapter\AbstractAdapter $dbd
  * @property \Phalcon\Db\Adapter\AbstractAdapter $dbr
- * @property \Phalcon\Events\ManagerInterface $eventsManager
+ * @property \Phalcon\Contracts\Events\Manager $eventsManager
  * @property \Phalcon\Flash\FlashInterface $flash
  * @property \Phalcon\Logger\LoggerInterface $logger
  * @property \Phalcon\Incubator\Mailer\Manager $mailer

src/Events/ConfiguredEventListeners.php

@@ -14,8 +14,8 @@
 namespace PhalconKit\Events;
 
 use Phalcon\Di\InjectionAwareInterface;
+use Phalcon\Contracts\Events\Manager as EventsManagerContract;
 use Phalcon\Events\Manager;
-use Phalcon\Events\ManagerInterface;
 use PhalconKit\Di\DiInterface;
 use PhalconKit\Exception\ConfigurationException;
 
@@ -63,14 +63,14 @@ private function __construct()
      * @param DiInterface $di Container used to resolve listener services and
      *     inject DI into listener objects that implement Phalcon's
      *     `InjectionAwareInterface`.
-     * @param ManagerInterface $eventsManager Events manager that receives the
+     * @param EventsManagerContract $eventsManager Events manager that receives the
      *     listener attachments.
      * @param array<array-key, mixed> $listeners Event-type map from config.
      *
      * @throws ConfigurationException When an event type, listener definition,
      *     listener class, listener service, or priority is invalid.
      */
-    public static function attach(DiInterface $di, ManagerInterface $eventsManager, array $listeners): void
+    public static function attach(DiInterface $di, EventsManagerContract $eventsManager, array $listeners): void
     {
         if ($listeners === []) {
             return;

src/Events/EventsAwareTrait.php

@@ -14,7 +14,7 @@
 namespace PhalconKit\Events;
 
 use Phalcon\Di\Di;
-use Phalcon\Events\ManagerInterface;
+use Phalcon\Contracts\Events\Manager as EventsManagerContract;
 use PhalconKit\Exception\InvalidArgumentException;
 use PhalconKit\Support\Helper;
 use PhalconKit\Support\Slug;
@@ -34,20 +34,20 @@ trait EventsAwareTrait
     /**
      * The event manager responsible for handling and triggering events.
      */
-    protected ?ManagerInterface $eventsManager;
+    protected ?EventsManagerContract $eventsManager;
 
     /**
      * Set the events manager
      */
-    public function setEventsManager(ManagerInterface $manager): void
+    public function setEventsManager(EventsManagerContract $manager): void
     {
         $this->eventsManager = $manager;
     }
 
     /**
      * Get the events manager.
      */
-    public function getEventsManager(): ?ManagerInterface
+    public function getEventsManager(): ?EventsManagerContract
     {
         $this->eventsManager ??= Di::getDefault()->get('eventsManager');
         return $this->eventsManager;
@@ -101,8 +101,10 @@ public function fire(string $task, mixed $data = null, bool $cancelable = false)
         $eventType = $this->getEventsPrefix() . ':' . $task;
         $eventsManager = $this->getEventsManager();
 
-        if (!$eventsManager instanceof ManagerInterface) {
-            throw new InvalidArgumentException("Events manager must be an instance of '" . ManagerInterface::class . "'.");
+        if (!$eventsManager instanceof EventsManagerContract) {
+            throw new InvalidArgumentException(
+                "Events manager must be an instance of '" . EventsManagerContract::class . "'."
+            );
         }
 
         return $eventsManager->fire($eventType, $this, $data, $cancelable);

src/Mvc/Controller/Traits/Behavior.php

@@ -13,10 +13,10 @@
 
 namespace PhalconKit\Mvc\Controller\Traits;
 
+use Phalcon\Contracts\Events\Manager as EventsManagerContract;
 use Phalcon\Di\Injectable;
 use Phalcon\Dispatcher\AbstractDispatcher;
 use Phalcon\Events\Manager;
-use Phalcon\Events\ManagerInterface;
 use Phalcon\Mvc\Dispatcher as MvcDispatcher;
 use PhalconKit\Acl\PermissionName;
 use PhalconKit\Mvc\Controller\Attributes\PermissionAttributeResolver;
@@ -118,10 +118,10 @@ public function attachBehaviors(array $behaviors = [], ?string $eventType = null
         }
     }
 
-    protected function getOrCreateEventsManager(): ManagerInterface
+    protected function getOrCreateEventsManager(): EventsManagerContract
     {
         $eventsManager = $this->getEventsManager();
-        if ($eventsManager instanceof ManagerInterface) {
+        if ($eventsManager instanceof EventsManagerContract) {
             return $eventsManager;
         }
 
@@ -130,7 +130,7 @@ protected function getOrCreateEventsManager(): ManagerInterface
             $eventsManager = $di->getShared('eventsManager');
         }
 
-        if (!$eventsManager instanceof ManagerInterface) {
+        if (!$eventsManager instanceof Manager) {
             $eventsManager = new Manager();
         }
 

src/Mvc/Model/Traits/Abstracts/AbstractEventsManager.php

@@ -13,13 +13,13 @@
 
 namespace PhalconKit\Mvc\Model\Traits\Abstracts;
 
-use Phalcon\Events\ManagerInterface;
+use Phalcon\Contracts\Events\Manager as EventsManagerContract;
 
 trait AbstractEventsManager
 {
     use AbstractInjectable;
 
-    abstract public function getEventsManager(): ?ManagerInterface;
+    abstract public function getEventsManager(): ?EventsManagerContract;
 
     abstract public function fireEventCancel(string $eventName): bool;