Return value of artisan handle function console command

Question

I created an artisan command using this command:

php artisan make:command --command=custom:command SomeCustomCommand

After I ran the command it created the file below:

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;

class SomeCustomCommand extends Command
{
    /**
     * The name and signature of the console command.
     *
     * @var string
     */
    protected $signature = 'custom:command';

    /**
     * The console command description.
     *
     * @var string
     */
    protected $description = 'Command description';

    /**
     * Create a new command instance.
     *
     * @return void
     */
    public function __construct()
    {
        parent::__construct();
    }

    /**
     * Execute the console command.
     *
     * @return int
     */
    public function handle()
    {
        return 0;
    }
}

I noticed that by default the handle method returns an int. Does this mean something? If I return 0 it mean error then 1 if success? I'm browsing the laravel documentation and it doesn't explain what should be the return of the handle function.

Answer 1

Although returned value does not impact command execution in CLI, integer values that can be returned from command handle() method 0, 1 or 2 have specific meaning.

Please have a look at the parent class. Illuminate\Console\Command extends Symfony\Component\Console\Command\Command where you can find public constants that can be used (and should be used in my opinion) when you return integer value in your command handle() method. It makes your command logically complete.

public const SUCCESS = 0;
public const FAILURE = 1;
public const INVALID = 2;

I usually do something like:

    /**
     * Execute the console command.
     *
     * @return int
     */
    public function handle(): int
    {
        $this->info('Send Toolkit Report Command');
        $this->info($this->description);
        $this->info('Processing...');

        try {
            $email = $this->argument('email');

            /** @var User|null $user */
            $user = User::query()->where('email', '=', $email)->first();

            if (!$user) {
                $warning = sprintf("User with given email '%s' does not exist", $email);
                $this->warn($warning);
                Log::warning(get_class($this));
                Log::warning($warning);

                return self::INVALID;
            }

            GenerateToolkitReport::dispatch($user);
        } catch (\Throwable $exception) {
            $this->error('Command failed with error:');
            $this->error($exception->getMessage());
            $this->error('Please check the logs!');
            Log::error($exception);

            return self::FAILURE;
        }

        $this->info('Toolkit Report generation has been dispatched to the queue.');
        $this->info('Successfully processed!');

        return self::SUCCESS;
    }

Answer 2

You can return whatever you like there, depending on what/where you call it from, I've seen people return a bool there as well as data or even nothing.

I think this is more of an opinion based subject. Personally, I return a bool as it fits what I use them for in my projects as I use real time notifications for command handle failures/exceptions

For example if you were to call a command via another class using Artisan::call() you may decide on running logic dependant on the actions your command has completed (this can be used to check for exit codes). OR you can catch any exceptions and handle them. You don't need to return from handle() in your console command for this to work.

    try {
        Artisan::call($object->command);
    } catch (ArtisanCommandException $e) {
        Log::error($e);
    }

    //note ArtisanCommandException is custom

See: https://laravel.com/docs/8.x/artisan#programmatically-executing-commands