feat(event): add interruptable contract for events which provides eve…

…nts with a mean to interrupt the event chain and provide a reason for it

packages/event/src/Charcoal/Event/InterruptableEventInterface.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace Charcoal\Event;
+
+use Stringable;
+
+/**
+ * Interface: InterruptableEventInterface
+ * @package Charcoal\Event
+ */
+interface InterruptableEventInterface
+{
+    public function isInterrupted(): bool;
+
+    /**
+     * @return string|Stringable
+     */
+    public function reason();
+}

packages/event/src/Charcoal/Event/InterruptableEventTrait.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace Charcoal\Event;
+
+use Stringable;
+
+/**
+ * Trait: InterruptableEventTrait
+ * @package Charcoal\Event
+ */
+trait InterruptableEventTrait
+{
+    private bool $interrupted = false;
+
+    /**
+     * @var string|Stringable
+     */
+    private $reason;
+
+    /**
+     * @param string|Stringable $reason
+     * @return void
+     */
+    public function interrupt($reason)
+    {
+        $this->reason = $reason;
+
+        $this->interrupted = true;
+    }
+
+    public function isInterrupted(): bool
+    {
+        return $this->interrupted;
+    }
+
+    /**
+     * @return string|Stringable
+     */
+    public function reason()
+    {
+        return $this->reason;
+    }
+}