[ 11.x ] Adds ability to manually fail a command from outside the han…

…dle() method (#51435)

* Add ManuallyFailedException to Console

* set up tests for manually failing a command

* implement manual test failing

* lint

* fixes and formatting

---------

Co-authored-by: Taylor Otwell <[email protected]>

src/Illuminate/Console/Command.php

@@ -9,6 +9,7 @@
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
+use Throwable;
 
 class Command extends SymfonyCommand
 {
@@ -210,6 +211,10 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 
         try {
             return (int) $this->laravel->call([$this, $method]);
+        } catch (ManuallyFailedException $e) {
+            $this->components->error($e->getMessage());
+
+            return static::FAILURE;
         } finally {
             if ($this instanceof Isolatable && $this->option('isolated') !== false) {
                 $this->commandIsolationMutex()->forget($this);
@@ -254,6 +259,25 @@ protected function resolveCommand($command)
         return $command;
     }
 
+    /**
+     * Fail the command manually.
+     *
+     * @param  \Throwable|string|null  $exception
+     * @return void
+     */
+    public function fail(Throwable|string|null $exception = null)
+    {
+        if (is_null($exception)) {
+            $exception = 'Command failed manually.';
+        }
+
+        if (is_string($exception)) {
+            $exception = new ManuallyFailedException($exception);
+        }
+
+        throw $exception;
+    }
+
     /**
      * {@inheritdoc}
      *

src/Illuminate/Console/ManuallyFailedException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Illuminate\Console;
+
+use RuntimeException;
+
+class ManuallyFailedException extends RuntimeException
+{
+    //
+}

src/Illuminate/Foundation/Console/ClosureCommand.php

@@ -4,6 +4,7 @@
 
 use Closure;
 use Illuminate\Console\Command;
+use Illuminate\Console\ManuallyFailedException;
 use Illuminate\Support\Facades\Schedule;
 use Illuminate\Support\Traits\ForwardsCalls;
 use ReflectionFunction;
@@ -58,9 +59,15 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             }
         }
 
-        return (int) $this->laravel->call(
-            $this->callback->bindTo($this, $this), $parameters
-        );
+        try {
+            return (int) $this->laravel->call(
+                $this->callback->bindTo($this, $this), $parameters
+            );
+        } catch (ManuallyFailedException $e) {
+            $this->components->error($e->getMessage());
+
+            return static::FAILURE;
+        }
     }
 
     /**

tests/Integration/Console/CommandManualFailTest.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace Illuminate\Tests\Integration\Console;
+
+use Illuminate\Console\Application as Artisan;
+use Illuminate\Console\Command;
+use Illuminate\Console\ManuallyFailedException;
+use Orchestra\Testbench\TestCase;
+
+class CommandManualFailTest extends TestCase
+{
+    protected function setUp(): void
+    {
+        Artisan::starting(function ($artisan) {
+            $artisan->resolveCommands([
+                FailingCommandStub::class,
+            ]);
+        });
+
+        parent::setUp();
+    }
+
+    public function testFailArtisanCommandManually()
+    {
+        $this->artisan('app:fail')->assertFailed();
+    }
+
+    public function testCreatesAnExceptionFromString()
+    {
+        $this->expectException(ManuallyFailedException::class);
+        $command = new Command;
+        $command->fail('Whoops!');
+    }
+
+    public function testCreatesAnExceptionFromNull()
+    {
+        $this->expectException(ManuallyFailedException::class);
+        $command = new Command;
+        $command->fail();
+    }
+}
+
+class FailingCommandStub extends Command
+{
+    protected $signature = 'app:fail';
+
+    public function handle()
+    {
+        $this->trigger_failure();
+
+        // This should never be reached.
+        return static::SUCCESS;
+    }
+
+    protected function trigger_failure()
+    {
+        $this->fail('Whoops!');
+    }
+}