Broadcasting Utilities (#55967)

* work on broadcasting helpers and rescue contract

* Apply fixes from StyleCI

* work on broadcasting helpers and rescue contract

* Apply fixes from StyleCI

* test broadcast_if

* more tests

* Rename var

---------

Co-authored-by: StyleCI Bot <bot@styleci.io>

Author: taylorotwell

src/Illuminate/Broadcasting/BroadcastManager.php

@@ -14,6 +14,7 @@
 use Illuminate\Contracts\Broadcasting\Factory as FactoryContract;
 use Illuminate\Contracts\Broadcasting\ShouldBeUnique;
 use Illuminate\Contracts\Broadcasting\ShouldBroadcastNow;
+use Illuminate\Contracts\Broadcasting\ShouldRescue;
 use Illuminate\Contracts\Bus\Dispatcher as BusDispatcherContract;
 use Illuminate\Contracts\Cache\Repository as Cache;
 use Illuminate\Contracts\Foundation\CachesRoutes;
@@ -178,7 +179,12 @@ public function queue($event)
             (is_object($event) &&
              method_exists($event, 'shouldBroadcastNow') &&
              $event->shouldBroadcastNow())) {
-            return $this->app->make(BusDispatcherContract::class)->dispatchNow(new BroadcastEvent(clone $event));
+            $dispatch = fn () => $this->app->make(BusDispatcherContract::class)
+                ->dispatchNow(new BroadcastEvent(clone $event));
+
+            return $event instanceof ShouldRescue
+                ? $this->rescue($dispatch)
+                : $dispatch();
         }
 
         $queue = null;
@@ -201,9 +207,13 @@ public function queue($event)
             }
         }
 
-        $this->app->make('queue')
+        $push = fn () => $this->app->make('queue')
             ->connection($event->connection ?? null)
             ->pushOn($queue, $broadcastEvent);
+
+        $event instanceof ShouldRescue
+            ? $this->rescue($push)
+            : $push();
     }
 
     /**
@@ -475,6 +485,21 @@ public function extend($driver, Closure $callback)
         return $this;
     }
 
+    /**
+     * Execute the given callback using "rescue" if possible.
+     *
+     * @param  \Closure  $callback
+     * @return mixed
+     */
+    protected function rescue(Closure $callback)
+    {
+        if (function_exists('rescue')) {
+            return rescue($callback);
+        }
+
+        return $callback();
+    }
+
     /**
      * Get the application instance used by the manager.
      *

src/Illuminate/Broadcasting/FakePendingBroadcast.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace Illuminate\Broadcasting;
+
+class FakePendingBroadcast extends PendingBroadcast
+{
+    /**
+     * Create a new pending broadcast instance.
+     */
+    public function __construct()
+    {
+        //
+    }
+
+    /**
+     * Broadcast the event using a specific broadcaster.
+     *
+     * @param  string|null  $connection
+     * @return $this
+     */
+    public function via($connection = null)
+    {
+        return $this;
+    }
+
+    /**
+     * Broadcast the event to everyone except the current user.
+     *
+     * @return $this
+     */
+    public function toOthers()
+    {
+        return $this;
+    }
+
+    /**
+     * Handle the object's destruction.
+     *
+     * @return void
+     */
+    public function __destruct()
+    {
+        //
+    }
+}

src/Illuminate/Contracts/Broadcasting/ShouldRescue.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Illuminate\Contracts\Broadcasting;
+
+interface ShouldRescue
+{
+    //
+}

src/Illuminate/Foundation/helpers.php

@@ -1,5 +1,6 @@
 <?php
 
+use Illuminate\Broadcasting\FakePendingBroadcast;
 use Illuminate\Container\Container;
 use Illuminate\Contracts\Auth\Access\Gate;
 use Illuminate\Contracts\Auth\Factory as AuthFactory;
@@ -32,7 +33,6 @@
      *
      * @param  \Symfony\Component\HttpFoundation\Response|\Illuminate\Contracts\Support\Responsable|int  $code
      * @param  string  $message
-     * @param  array  $headers
      * @return never
      *
      * @throws \Symfony\Component\HttpKernel\Exception\HttpException
@@ -58,7 +58,6 @@ function abort($code, $message = '', array $headers = [])
      * @param  bool  $boolean
      * @param  \Symfony\Component\HttpFoundation\Response|\Illuminate\Contracts\Support\Responsable|int  $code
      * @param  string  $message
-     * @param  array  $headers
      * @return void
      *
      * @throws \Symfony\Component\HttpKernel\Exception\HttpException
@@ -79,7 +78,6 @@ function abort_if($boolean, $code, $message = '', array $headers = [])
      * @param  bool  $boolean
      * @param  \Symfony\Component\HttpFoundation\Response|\Illuminate\Contracts\Support\Responsable|int  $code
      * @param  string  $message
-     * @param  array  $headers
      * @return void
      *
      * @throws \Symfony\Component\HttpKernel\Exception\HttpException
@@ -115,7 +113,6 @@ function action($name, $parameters = [], $absolute = true)
      * @template TClass of object
      *
      * @param  string|class-string<TClass>|null  $abstract
-     * @param  array  $parameters
      * @return ($abstract is class-string<TClass> ? TClass : ($abstract is null ? \Illuminate\Foundation\Application : mixed))
      */
     function app($abstract = null, array $parameters = [])
@@ -227,6 +224,42 @@ function broadcast($event = null)
     }
 }
 
+if (! function_exists('broadcast_if')) {
+    /**
+     * Begin broadcasting an event if the given condition is true.
+     *
+     * @param  bool  $boolean
+     * @param  mixed|null  $event
+     * @return \Illuminate\Broadcasting\PendingBroadcast
+     */
+    function broadcast_if($boolean, $event = null)
+    {
+        if ($boolean) {
+            return app(BroadcastFactory::class)->event($event);
+        } else {
+            return new FakePendingBroadcast;
+        }
+    }
+}
+
+if (! function_exists('broadcast_unless')) {
+    /**
+     * Begin broadcasting an event unless the given condition is true.
+     *
+     * @param  bool  $boolean
+     * @param  mixed|null  $event
+     * @return \Illuminate\Broadcasting\PendingBroadcast
+     */
+    function broadcast_unless($boolean, $event = null)
+    {
+        if (! $boolean) {
+            return app(BroadcastFactory::class)->event($event);
+        } else {
+            return new FakePendingBroadcast;
+        }
+    }
+}
+
 if (! function_exists('cache')) {
     /**
      * Get / set the specified cache value.
@@ -406,9 +439,6 @@ function decrypt($value, $unserialize = true)
     /**
      * Defer execution of the given callback.
      *
-     * @param  callable|null  $callback
-     * @param  string|null  $name
-     * @param  bool  $always
      * @return \Illuminate\Support\Defer\DeferredCallback
      */
     function defer(?callable $callback = null, ?string $name = null, bool $always = false)
@@ -521,7 +551,6 @@ function info($message, $context = [])
      * Log a debug message to the logs.
      *
      * @param  string|null  $message
-     * @param  array  $context
      * @return ($message is null ? \Illuminate\Log\LogManager : null)
      */
     function logger($message = null, array $context = [])
@@ -799,7 +828,6 @@ function rescue(callable $callback, $rescue = null, $report = true)
      * @template TClass of object
      *
      * @param  string|class-string<TClass>  $name
-     * @param  array  $parameters
      * @return ($name is class-string<TClass> ? TClass : mixed)
      */
     function resolve($name, array $parameters = [])
@@ -827,7 +855,6 @@ function resource_path($path = '')
      *
      * @param  \Illuminate\Contracts\View\View|string|array|null  $content
      * @param  int  $status
-     * @param  array  $headers
      * @return ($content is null ? \Illuminate\Contracts\Routing\ResponseFactory : \Illuminate\Http\Response)
      */
     function response($content = null, $status = 200, array $headers = [])
@@ -975,7 +1002,6 @@ function trans($key = null, $replace = [], $locale = null)
      *
      * @param  string  $key
      * @param  \Countable|int|float|array  $number
-     * @param  array  $replace
      * @param  string|null  $locale
      * @return string
      */
@@ -1041,10 +1067,6 @@ function url($path = null, $parameters = [], $secure = null)
     /**
      * Create a new Validator instance.
      *
-     * @param  array|null  $data
-     * @param  array  $rules
-     * @param  array  $messages
-     * @param  array  $attributes
      * @return ($data is null ? \Illuminate\Contracts\Validation\Factory : \Illuminate\Contracts\Validation\Validator)
      */
     function validator(?array $data = null, array $rules = [], array $messages = [], array $attributes = [])

tests/Foundation/FoundationHelpersTest.php

@@ -3,6 +3,7 @@
 namespace Illuminate\Tests\Foundation;
 
 use Exception;
+use Illuminate\Broadcasting\FakePendingBroadcast;
 use Illuminate\Container\Container;
 use Illuminate\Contracts\Cache\Repository as CacheRepository;
 use Illuminate\Contracts\Config\Repository;
@@ -295,4 +296,9 @@ public function testAbortReceivesCodeAsInteger()
 
         abort($code, $message, $headers);
     }
+
+    public function testBroadcastIfReturnsFakeOnFalse()
+    {
+        $this->assertInstanceOf(FakePendingBroadcast::class, broadcast_if(false, 'foo'));
+    }
 }

tests/Integration/Broadcasting/BroadcastManagerTest.php

@@ -10,6 +10,7 @@
 use Illuminate\Contracts\Broadcasting\ShouldBeUnique;
 use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
 use Illuminate\Contracts\Broadcasting\ShouldBroadcastNow;
+use Illuminate\Contracts\Broadcasting\ShouldRescue;
 use Illuminate\Contracts\Cache\Repository as Cache;
 use Illuminate\Support\Facades\Broadcast;
 use Illuminate\Support\Facades\Bus;
@@ -41,6 +42,28 @@ public function testEventsCanBeBroadcast()
         Queue::assertPushed(BroadcastEvent::class);
     }
 
+    public function testEventsCanBeRescued()
+    {
+        Bus::fake();
+        Queue::fake();
+
+        Broadcast::queue(new TestEventRescue);
+
+        Bus::assertNotDispatched(BroadcastEvent::class);
+        Queue::assertPushed(BroadcastEvent::class);
+    }
+
+    public function testNowEventsCanBeRescued()
+    {
+        Bus::fake();
+        Queue::fake();
+
+        Broadcast::queue(new TestEventNowRescue);
+
+        Bus::assertDispatched(BroadcastEvent::class);
+        Queue::assertNotPushed(BroadcastEvent::class);
+    }
+
     public function testUniqueEventsCanBeBroadcast()
     {
         Bus::fake();
@@ -124,3 +147,29 @@ public function broadcastOn()
         //
     }
 }
+
+class TestEventRescue implements ShouldBroadcast, ShouldRescue
+{
+    /**
+     * Get the channels the event should broadcast on.
+     *
+     * @return \Illuminate\Broadcasting\Channel|\Illuminate\Broadcasting\Channel[]
+     */
+    public function broadcastOn()
+    {
+        //
+    }
+}
+
+class TestEventNowRescue implements ShouldBroadcastNow, ShouldRescue
+{
+    /**
+     * Get the channels the event should broadcast on.
+     *
+     * @return \Illuminate\Broadcasting\Channel|\Illuminate\Broadcasting\Channel[]
+     */
+    public function broadcastOn()
+    {
+        //
+    }
+}