From 979b9371fa41535e9c6b0facd16389f63e5ab193 Mon Sep 17 00:00:00 2001
From: techmahedy <mahedy150101@gmail.com>
Date: Fri, 30 Oct 2026 20:56:56 +0600
Subject: [PATCH] Introduce a signal bus contract

---
 src/Phaseolies/Database/Database.php          |  6 +-
 src/Phaseolies/Helpers/helpers.php            |  2 +-
 src/Phaseolies/Launchers/FacadeLauncher.php   |  7 +-
 .../Signals/Contracts/SignalBusInterface.php  | 75 +++++++++++++++++++
 src/Phaseolies/Signals/SignalBus.php          |  3 +-
 src/Phaseolies/Support/Facades/Signal.php     |  8 +-
 tests/Signals/SignalBusTest.php               | 33 ++++++++
 7 files changed, 123 insertions(+), 11 deletions(-)
 create mode 100644 src/Phaseolies/Signals/Contracts/SignalBusInterface.php

diff --git a/src/Phaseolies/Database/Database.php b/src/Phaseolies/Database/Database.php
index 7db7417a..43b01c16 100644
--- a/src/Phaseolies/Database/Database.php
+++ b/src/Phaseolies/Database/Database.php
@@ -37,7 +37,7 @@ class Database
     /**
      * Signals waiting for a transaction to settle, per connection and nesting level
      *
-     * @var array<string, array<int, array<int, array{0: \Phaseolies\Signals\SignalBus, 1: object}>>>
+     * @var array<string, array<int, array<int, array{0: \Phaseolies\Signals\Contracts\SignalBusInterface, 1: object}>>>
      */
     protected static $pendingSignals = [];
 
@@ -245,12 +245,12 @@ public function rollBack(): void
     /**
      * Hold a signal until the open transaction on a connection settles
      *
-     * @param \Phaseolies\Signals\SignalBus $bus
+     * @param \Phaseolies\Signals\Contracts\SignalBusInterface $bus
      * @param object $signal
      * @param string|null $connection
      * @return bool
      */
-    public static function stageSignal(\Phaseolies\Signals\SignalBus $bus, object $signal, ?string $connection = null): bool
+    public static function stageSignal(\Phaseolies\Signals\Contracts\SignalBusInterface $bus, object $signal, ?string $connection = null): bool
     {
         $connection = $connection ?: config('database.default');
         $level = static::$transactions[$connection] ?? 0;
diff --git a/src/Phaseolies/Helpers/helpers.php b/src/Phaseolies/Helpers/helpers.php
index 0014b577..4251dd46 100644
--- a/src/Phaseolies/Helpers/helpers.php
+++ b/src/Phaseolies/Helpers/helpers.php
@@ -96,7 +96,7 @@ function defer(callable $callback)
      * Get the signal bus, or emit a signal when one is given
      *
      * @param object|null $signal
-     * @return \Phaseolies\Signals\SignalBus|void
+     * @return \Phaseolies\Signals\Contracts\SignalBusInterface|void
      */
     function signal(?object $signal = null)
     {
diff --git a/src/Phaseolies/Launchers/FacadeLauncher.php b/src/Phaseolies/Launchers/FacadeLauncher.php
index 4a562367..29fc90ba 100644
--- a/src/Phaseolies/Launchers/FacadeLauncher.php
+++ b/src/Phaseolies/Launchers/FacadeLauncher.php
@@ -11,6 +11,7 @@
 use Phaseolies\Support\Storage\StorageFileService;
 use Phaseolies\Support\Storage\Contracts\StorageInterface;
 use Phaseolies\Signals\SignalBus;
+use Phaseolies\Signals\Contracts\SignalBusInterface;
 use Phaseolies\Support\Session;
 use Phaseolies\Session\Contracts\SessionInterface;
 use Phaseolies\Support\Mail\MailService;
@@ -131,9 +132,11 @@ public function register()
         // This handles db related jobs
         $this->app->singleton('db', Database::class);
 
-        // Bind the 'signal' service to a singleton instance of the SignalBus class.
+        // Bind the signal bus contract to a singleton implementation and
+        // retain the existing 'signal' service name as an alias.
         // This handles signals that can wait for a database transaction to settle
-        $this->app->singleton('signal', SignalBus::class);
+        $this->app->singleton(SignalBusInterface::class, SignalBus::class);
+        $this->app->alias(SignalBusInterface::class, 'signal');
 
         // Bind the 'app' service to a singleton instance of the Application class.
         // This handles app related jobs
diff --git a/src/Phaseolies/Signals/Contracts/SignalBusInterface.php b/src/Phaseolies/Signals/Contracts/SignalBusInterface.php
new file mode 100644
index 00000000..991adf77
--- /dev/null
+++ b/src/Phaseolies/Signals/Contracts/SignalBusInterface.php
@@ -0,0 +1,75 @@
+<?php
+
+namespace Phaseolies\Signals\Contracts;
+
+interface SignalBusInterface
+{
+    /**
+     * Register a listener for a signal class or interface.
+     *
+     * @param string $signal
+     * @param callable|array|string $listener
+     * @param int $priority
+     * @return self
+     * @throws \InvalidArgumentException
+     */
+    public function on(string $signal, callable|array|string $listener, int $priority = 0): self;
+
+    /**
+     * Remove every listener of a signal, or all listeners when none is given.
+     *
+     * @param string|null $signal
+     * @return self
+     */
+    public function forget(?string $signal = null): self;
+
+    /**
+     * Determine if any listener would receive the given signal.
+     *
+     * @param object|string $signal
+     * @return bool
+     */
+    public function hasListeners(object|string $signal): bool;
+
+    /**
+     * Emit a signal.
+     *
+     * @param object $signal
+     * @return void
+     */
+    public function emit(object $signal): void;
+
+    /**
+     * Emit a signal right away, ignoring #[DeliverOnSettle] and any open transaction.
+     *
+     * @param object $signal
+     * @return void
+     */
+    public function emitNow(object $signal): void;
+
+    /**
+     * Emit a signal once the open transaction on a connection settles.
+     *
+     * @param object $signal
+     * @param string|null $connection
+     * @return bool
+     */
+    public function emitOnSettle(object $signal, ?string $connection = null): bool;
+
+    /**
+     * Deliver a signal whose transaction has just committed.
+     *
+     * @param object $signal
+     * @return void
+     * @internal Called by the database layer
+     */
+    public function settle(object $signal): void;
+
+    /**
+     * Set a custom reporter for listener failures that happen after a commit.
+     *
+     * @param callable(\Throwable, object): void|null $reporter
+     * @return self
+     */
+    public function reportFailuresUsing(?callable $reporter): self;
+}
diff --git a/src/Phaseolies/Signals/SignalBus.php b/src/Phaseolies/Signals/SignalBus.php
index 7dfd3826..943bddd8 100644
--- a/src/Phaseolies/Signals/SignalBus.php
+++ b/src/Phaseolies/Signals/SignalBus.php
@@ -4,8 +4,9 @@
 
 use Phaseolies\Database\Database;
 use Phaseolies\Signals\Attributes\DeliverOnSettle;
+use Phaseolies\Signals\Contracts\SignalBusInterface;
 
-class SignalBus
+class SignalBus implements SignalBusInterface
 {
     /**
      * Registered listeners, keyed by signal class or interface name
diff --git a/src/Phaseolies/Support/Facades/Signal.php b/src/Phaseolies/Support/Facades/Signal.php
index 6d5388a4..b3fe0455 100644
--- a/src/Phaseolies/Support/Facades/Signal.php
+++ b/src/Phaseolies/Support/Facades/Signal.php
@@ -5,15 +5,15 @@
 use Phaseolies\Facade\BaseFacade;
 
 /**
- * @method static \Phaseolies\Signals\SignalBus on(string $signal, callable|array|string $listener, int $priority = 0)
- * @method static \Phaseolies\Signals\SignalBus forget(?string $signal = null)
+ * @method static \Phaseolies\Signals\Contracts\SignalBusInterface on(string $signal, callable|array|string $listener, int $priority = 0)
+ * @method static \Phaseolies\Signals\Contracts\SignalBusInterface forget(?string $signal = null)
  * @method static bool hasListeners(object|string $signal)
  * @method static void emit(object $signal)
  * @method static void emitNow(object $signal)
  * @method static bool emitOnSettle(object $signal, ?string $connection = null)
- * @method static \Phaseolies\Signals\SignalBus reportFailuresUsing(?callable $reporter)
+ * @method static \Phaseolies\Signals\Contracts\SignalBusInterface reportFailuresUsing(?callable $reporter)
  *
- * @see \Phaseolies\Signals\SignalBus
+ * @see \Phaseolies\Signals\Contracts\SignalBusInterface
  */
 class Signal extends BaseFacade
 {
diff --git a/tests/Signals/SignalBusTest.php b/tests/Signals/SignalBusTest.php
index 5c1af9e1..ad6b3308 100644
--- a/tests/Signals/SignalBusTest.php
+++ b/tests/Signals/SignalBusTest.php
@@ -3,7 +3,12 @@
 namespace Tests\Unit\Signals;
 
 use PHPUnit\Framework\TestCase;
+use Phaseolies\Application;
+use Phaseolies\DI\Container;
+use Phaseolies\Launchers\FacadeLauncher;
+use Phaseolies\Signals\Contracts\SignalBusInterface;
 use Phaseolies\Signals\SignalBus;
+use ReflectionClass;
 
 interface TracksOrders {}
 
@@ -39,6 +44,34 @@ protected function setUp(): void
         InvokableListener::$seen = [];
     }
 
+    public function testSignalBusConformsToTheContract(): void
+    {
+        $this->assertInstanceOf(SignalBusInterface::class, $this->bus);
+    }
+
+    public function testApplicationBindsTheSignalContractAndLegacyServiceNameToTheSameSingleton(): void
+    {
+        $app = $this->getMockBuilder(Application::class)->disableOriginalConstructor()->onlyMethods([])->getMock();
+        (new ReflectionClass(Container::class))->getConstructor()->invoke($app);
+        $previous = Container::getInstance();
+        Container::setInstance($app);
+        $originalAppUrl = getenv('APP_URL');
+
+        try {
+            putenv('APP_URL=http://localhost');
+            (new FacadeLauncher($app))->register();
+
+            $contract = $app->get(SignalBusInterface::class);
+
+            $this->assertInstanceOf(SignalBus::class, $contract);
+            $this->assertSame($contract, $app->get('signal'));
+            $this->assertSame($contract, signal());
+        } finally {
+            Container::setInstance($previous);
+            $originalAppUrl === false ? putenv('APP_URL') : putenv("APP_URL={$originalAppUrl}");
+        }
+    }
+
     public function testHigherPriorityListenersRunFirst(): void
     {
         $order = [];