[ 11.x ] Adds ability to manually fail a command from outside the handle() method

[ProjektGopher]

In a large and complex artisan command where smaller bits are extracted into separate methods (each of which is a possible failure point), we have a couple of options to exit with a non-zero exit code without dumping the entire Exception.

We can wrap the method call in a try/catch, and return in the catch block.

    public function handle()
    {
        try {
            $this->trigger_failure();
        } catch (ManuallyFailedException $e) {
            $this->error($e->getMessage());

            return static::FAILURE;
        }
    }

    protected function trigger_failure()
    {
        throw new ManuallyFailedException("whoops!");
    }

We can use a return value and wrap it in an if block.

    public function handle()
    {
        [$result, $error] = $this->trigger_failure();
        if (!is_null($error)) {
            $this->error($error->message);

            return static::FAILURE;
        }
    }

    protected function trigger_failure()
    {
        return [false, (object) [
            'message' => 'whoops!',
        ]];
    }

These obviously work just fine, but it's a paper cut I've run into many times. The Queue has a $this->fail() convenience method, so I've implemented one on the Command class to mimic it. This new approach feels more readable, and more intuitive. Since we're only working with a custom Exception, backwards compatibility is fully maintained. Here's an example of this new method of failing a command outside of the handle() method:

    public function handle()
    {
        $this->trigger_failure();
    }

    protected function trigger_failure()
    {
        $this->fail('Whoops!');
    }

[taylorotwell]

@ProjektGopher feel like submitting a docs PR for this? 😊