Merge pull request #17030 from phalcon/T17019-ev-enhacements

T17006 ev enhacements

Author: niden

CHANGELOG-5.0.md

@@ -0,0 +1,52 @@
+
+/**
+ * This file is part of the Phalcon Framework.
+ *
+ * (c) Phalcon Team <team@phalcon.io>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+namespace Phalcon\Contracts\Events;
+
+/**
+ * Canonical contract for Phalcon\Events\Event.
+ */
+interface Event
+{
+    /**
+     * Gets event data
+     */
+    public function getData() -> var;
+
+    /**
+     * Gets event type
+     */
+    public function getType() -> var;
+
+    /**
+     * Check whether the event is cancelable
+     */
+    public function isCancelable() -> bool;
+
+    /**
+     * Check whether the event is currently stopped
+     */
+    public function isStopped() -> bool;
+
+    /**
+     * Sets event data
+     */
+    public function setData(var data = null) -> <Event>;
+
+    /**
+     * Sets event type
+     */
+    public function setType(string type) -> <Event>;
+
+    /**
+     * Stops the event preventing propagation
+     */
+    public function stop() -> <Event>;
+}

phalcon/Contracts/Events/Event.zep

@@ -0,0 +1,35 @@
+
+/**
+ * This file is part of the Phalcon Framework.
+ *
+ * (c) Phalcon Team <team@phalcon.io>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+namespace Phalcon\Contracts\Events;
+
+use Phalcon\Events\ManagerInterface;
+
+/**
+ * Canonical contract for Phalcon\Events\EventsAwareInterface. Implemented by
+ * components that accept an events manager and dispatch through it.
+ *
+ * Cross-references the legacy ManagerInterface (not the canonical Manager
+ * contract) to preserve LSP for the many AbstractEventsAware subclasses that
+ * already type-hint ManagerInterface. ManagerInterface extends Manager, so
+ * this remains type-compatible with any code that needs the canonical surface.
+ */
+interface EventsAware
+{
+    /**
+     * Returns the internal events manager
+     */
+    public function getEventsManager() -> <ManagerInterface> | null;
+
+    /**
+     * Sets the events manager
+     */
+    public function setEventsManager(<ManagerInterface> eventsManager) -> void;
+}

phalcon/Contracts/Events/EventsAware.zep

@@ -0,0 +1,123 @@
+
+/**
+ * This file is part of the Phalcon Framework.
+ *
+ * (c) Phalcon Team <team@phalcon.io>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+namespace Phalcon\Contracts\Events;
+
+/**
+ * Canonical contract for Phalcon\Events\Manager.
+ */
+interface Manager
+{
+    /**
+     * @var int
+     */
+    const DEFAULT_PRIORITY = 100;
+
+    /**
+     * Registers an event subscriber. The subscriber's getSubscribedEvents()
+     * map is parsed and each entry is attached through the regular listener
+     * pipeline.
+     */
+    public function addSubscriber(<Subscriber> subscriber) -> void;
+
+    /**
+     * Returns whether priority ordering is currently enabled.
+     */
+    public function arePrioritiesEnabled() -> bool;
+
+    /**
+     * Attach a listener to the events manager.
+     *
+     * @param object|callable handler
+     */
+    public function attach(
+        string eventType,
+        handler,
+        int priority = self::DEFAULT_PRIORITY
+    ) -> void;
+
+    /**
+     * Removes every registered subscriber and detaches each listener they
+     * contributed. Listeners attached via attach() are untouched.
+     */
+    public function clearSubscribers() -> void;
+
+    /**
+     * Toggle response collection on/off.
+     */
+    public function collectResponses(bool collect) -> void;
+
+    /**
+     * Detach a listener from the events manager.
+     *
+     * @param object|callable handler
+     */
+    public function detach(string eventType, handler) -> void;
+
+    /**
+     * Removes all listeners — globally or for a single event type.
+     */
+    public function detachAll(string type = null) -> void;
+
+    /**
+     * Toggle priority ordering on/off.
+     */
+    public function enablePriorities(bool enablePriorities) -> void;
+
+    /**
+     * Fires an event, notifying the active listeners.
+     *
+     * @param object source
+     * @param mixed  data
+     * @return mixed
+     */
+    public function fire(
+        string eventType,
+        object source,
+        var data = null,
+        bool cancelable = true
+    );
+
+    /**
+     * Returns all listeners attached to the given event type.
+     */
+    public function getListeners(string type) -> array;
+
+    /**
+     * Returns the responses recorded during the last fire (when collecting).
+     */
+    public function getResponses() -> array;
+
+    /**
+     * Returns the list of registered subscriber instances.
+     */
+    public function getSubscribers() -> array;
+
+    /**
+     * Check whether the given event type has any listeners.
+     */
+    public function hasListeners(string type) -> bool;
+
+    /**
+     * Check whether the manager is currently collecting responses.
+     */
+    public function isCollecting() -> bool;
+
+    /**
+     * Returns true when the given handler is an object or callable.
+     */
+    public function isValidHandler(var handler) -> bool;
+
+    /**
+     * Removes a previously registered subscriber. Detaches every listener the
+     * subscriber declared via getSubscribedEvents(). Idempotent.
+     */
+    public function removeSubscriber(<Subscriber> subscriber) -> void;
+}

phalcon/Contracts/Events/Manager.zep

@@ -0,0 +1,26 @@
+
+/**
+ * This file is part of the Phalcon Framework.
+ *
+ * (c) Phalcon Team <team@phalcon.io>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+namespace Phalcon\Contracts\Events;
+
+/**
+ * Phalcon's local mirror of PSR-14 StoppableEventInterface. Identical shape;
+ * not extended from the PSR interface because the Zephir extension cannot
+ * reference Composer-loaded interfaces at build time. A separate bridge
+ * package exposes a PSR-14 adapter.
+ */
+interface Stoppable
+{
+    /**
+     * Returns true when the event must stop propagating to subsequent
+     * listeners.
+     */
+    public function isPropagationStopped() -> bool;
+}

phalcon/Contracts/Events/Stoppable.zep

@@ -0,0 +1,43 @@
+
+/**
+ * This file is part of the Phalcon Framework.
+ *
+ * (c) Phalcon Team <team@phalcon.io>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+namespace Phalcon\Contracts\Events;
+
+/**
+ * Contract for event subscriber classes. A subscriber declares the events it
+ * wants to listen to via a static map; Events\Manager parses the map and
+ * attaches each entry as a regular listener.
+ *
+ * Accepted value shapes per event key:
+ *
+ *   'event:name' => 'methodName'
+ *   'event:name' => ['methodName', priority]
+ *   'event:name' => [
+ *       ['methodName1'],
+ *       ['methodName2', priority],
+ *   ]
+ *
+ * Keys can be either a Phalcon event string (e.g. "db:beforeQuery") or a
+ * fully qualified event class name.
+ *
+ * Wildcard subscriptions: Phalcon's manager fires both the prefix queue and
+ * the full-name queue (e.g. "db" is fired before "db:beforeQuery"). To
+ * subscribe to every event of a component, use the prefix as the key:
+ *
+ *   'db' => 'onAnyDbEvent'   // fires for db:beforeQuery, db:afterQuery, ...
+ */
+interface Subscriber
+{
+    /**
+     * Returns a map of event name => listener config. Called once per
+     * Manager::addSubscriber() / removeSubscriber() call.
+     */
+    public static function getSubscribedEvents() -> array;
+}

phalcon/Contracts/Events/Subscriber.zep

@@ -10,6 +10,8 @@
 
 namespace Phalcon\Events;
 
+use Phalcon\Contracts\Events\Stoppable;
+
 /**
  * This class offers contextual information of a fired event in the
  * EventsManager
@@ -23,7 +25,7 @@ namespace Phalcon\Events;
  * }
  * ```
  */
-class Event implements EventInterface
+final class Event implements EventInterface, Stoppable
 {
     /**
      * Is event cancelable?
@@ -65,13 +67,18 @@ class Event implements EventInterface
      *
      * @param object source
      */
-    public function __construct(string! type, var source = null, var data = null, bool cancelable = true)
-    {
+    public function __construct(
+        string type,
+        var source = null,
+        var data = null,
+        bool cancelable = true
+    ) {
         if unlikely null !== source && typeof source !== "object" {
             throw new Exception(
                 "The source of " . type . " event must be an object, got " . (typeof source)
             );
         }
+
         let this->type       = type,
             this->source     = source,
             this->data       = data,
@@ -107,6 +114,15 @@ class Event implements EventInterface
         return this->cancelable;
     }
 
+    /**
+     * Returns whether propagation must stop. PSR-14 alias backed by the same
+     * `stopped` flag as `isStopped()`; calling `stop()` flips both.
+     */
+    public function isPropagationStopped() -> bool
+    {
+        return this->stopped;
+    }
+
     /**
      * Check whether the event is currently stopped.
      */

phalcon/Events/Event.zep

@@ -10,43 +10,15 @@
 
 namespace Phalcon\Events;
 
+use Phalcon\Contracts\Events\Event as EventContract;
+
 /**
- * Interface for Phalcon\Events\Event class
+ * Phalcon\Events\EventInterface
+ *
+ * @psalm-suppress DeprecatedInterface
+ * @deprecated Will be removed in a future major release.
+ *             Use {@see \Phalcon\Contracts\Events\Event} instead.
  */
-interface EventInterface
+interface EventInterface extends EventContract
 {
-    /**
-     * Gets event data
-     */
-    public function getData() -> var;
-
-    /**
-     * Gets event type
-     */
-    public function getType() -> var;
-
-    /**
-     * Check whether the event is cancelable
-     */
-    public function isCancelable() -> bool;
-
-    /**
-     * Check whether the event is currently stopped
-     */
-    public function isStopped() -> bool;
-
-    /**
-     * Sets event data
-     */
-    public function setData(var data = null) -> <EventInterface>;
-
-    /**
-     * Sets event type
-     */
-    public function setType(string! type) -> <EventInterface>;
-
-    /**
-     * Stops the event preventing propagation
-     */
-    public function stop() -> <EventInterface>;
 }