Artisan Console

• Introduction
  • Tinker (REPL)
• Writing Commands
  • Generating Commands
  • Command Structure
  • Closure Commands
  • Isolatable Commands
• Defining Input Expectations
  • Arguments
  • Options
  • Input Arrays
  • Input Descriptions
  • Prompting for Missing Input
• Command I/O
  • Retrieving Input
  • Prompting for Input
  • Writing Output
• Registering Commands
• Programmatically Executing Commands
  • Calling Commands From Other Commands
• Signal Handling
• Stub Customization
• Events

Introduction

Artisan is the command line interface included with Laravel. Artisan exists at the root of your application as the artisan script and provides a number of helpful commands that can assist you while you build your application. To view a list of all available Artisan commands, you may use the list command:

php artisan list

Every command also includes a "help" screen which displays and describes the command's available arguments and options. To view a help screen, precede the name of the command with help:

php artisan help migrate

Laravel Sail

If you are using Laravel Sail as your local development environment, remember to use the sail command line to invoke Artisan commands. Sail will execute your Artisan commands within your application's Docker containers:

./vendor/bin/sail artisan list

Tinker (REPL)

Laravel Tinker is a powerful REPL for the Laravel framework, powered by the PsySH package.

Installation

All Laravel applications include Tinker by default. However, you may install Tinker using Composer if you have previously removed it from your application:

composer require laravel/tinker

Usage

Tinker allows you to interact with your entire Laravel application on the command line, including your Eloquent models, jobs, events, and more. To enter the Tinker environment, run the tinker Artisan command:

php artisan tinker

You can publish Tinker's configuration file using the vendor:publish command:

php artisan vendor:publish --provider="Laravel\Tinker\TinkerServiceProvider"

Command Allow List

Tinker utilizes an "allow" list to determine which Artisan commands are allowed to be run within its shell. By default, you may run the clear-compiled, down, env, inspire, migrate, migrate:install, up, and optimize commands. If you would like to allow more commands you may add them to the commands array in your tinker.php configuration file:

'commands' => [
    // App\Console\Commands\ExampleCommand::class,
],

Classes That Should Not Be Aliased

Typically, Tinker automatically aliases classes as you interact with them in Tinker. However, you may wish to never alias some classes. You may accomplish this by listing the classes in the dont_alias array of your tinker.php configuration file:

'dont_alias' => [
    App\Models\User::class,
],

Writing Commands

In addition to the commands provided with Artisan, you may build your own custom commands. Commands are typically stored in the app/Console/Commands directory; however, you are free to choose your own storage location as long as your commands can be loaded by Composer.

Generating Commands

To create a new command, you may use the make:command Artisan command. This command will create a new command class in the app/Console/Commands directory. Don't worry if this directory does not exist in your application - it will be created the first time you run the make:command Artisan command:

php artisan make:command SendEmails

Command Structure

After generating your command, you should define appropriate values for the signature and description properties of the class. These properties will be used when displaying your command on the list screen. The signature property also allows you to define your command's input expectations. The handle method will be called when your command is executed. You may place your command logic in this method.

Let's take a look at an example command. Note that we are able to request any dependencies we need via the command's handle method. The Laravel service container will automatically inject all dependencies that are type-hinted in this method's signature:

<?php
 
namespace App\Console\Commands;
 
use App\Models\User;
use App\Support\DripEmailer;
use Illuminate\Console\Command;
 
class SendEmails extends Command
{
    /**
     * The name and signature of the console command.
     *
     * @var string
     */
    protected $signature = 'mail:send {user}';
 
    /**
     * The console command description.
     *
     * @var string
     */
    protected $description = 'Send a marketing email to a user';
 
    /**
     * Execute the console command.
     */
    public function handle(DripEmailer $drip): void
    {
        $drip->send(User::find($this->argument('user')));
    }
}

Exit Codes

If nothing is returned from the handle method and the command executes successfully, the command will exit with a 0 exit code, indicating success. However, the handle method may optionally return an integer to manually specify command's exit code:

$this->error('Something went wrong.');
 
return 1;

If you would like to "fail" the command from any method within the command, you may utilize the fail method. The fail method will immediately terminate execution of the command and return an exit code of 1:

$this->fail('Something went wrong.');

Closure Commands

Closure based commands provide an alternative to defining console commands as classes. In the same way that route closures are an alternative to controllers, think of command closures as an alternative to command classes.

Even though the routes/console.php file does not define HTTP routes, it defines console based entry points (routes) into your application. Within this file, you may define all of your closure based console commands using the Artisan::command method. The command method accepts two arguments: the command signature and a closure which receives the command's arguments and options:

Artisan::command('mail:send {user}', function (string $user) {
    $this->info("Sending email to: {$user}!");
});

The closure is bound to the underlying command instance, so you have full access to all of the helper methods you would typically be able to access on a full command class.

Type-Hinting Dependencies

In addition to receiving your command's arguments and options, command closures may also type-hint additional dependencies that you would like resolved out of the service container:

use App\Models\User;
use App\Support\DripEmailer;
 
Artisan::command('mail:send {user}', function (DripEmailer $drip, string $user) {
    $drip->send(User::find($user));
});

Closure Command Descriptions

When defining a closure based command, you may use the purpose method to add a description to the command. This description will be displayed when you run the php artisan list or php artisan help commands:

Artisan::command('mail:send {user}', function (string $user) {
    // ...
})->purpose('Send a marketing email to a user');

Isolatable Commands

Sometimes you may wish to ensure that only one instance of a command can run at a time. To accomplish this, you may implement the Illuminate\Contracts\Console\Isolatable interface on your command class:

<?php
 
namespace App\Console\Commands;
 
use Illuminate\Console\Command;
use Illuminate\Contracts\Console\Isolatable;
 
class SendEmails extends Command implements Isolatable
{
    // ...
}

When a command is marked as Isolatable, Laravel will automatically add an --isolated option to the command. When the command is invoked with that option, Laravel will ensure that no other instances of that command are already running. Laravel accomplishes this by attempting to acquire an atomic lock using your application's default cache driver. If other instances of the command are running, the command will not execute; however, the command will still exit with a successful exit status code:

php artisan mail:send 1 --isolated

If you would like to specify the exit status code that the command should return if it is not able to execute, you may provide the desired status code via the isolated option:

php artisan mail:send 1 --isolated=12

Lock ID

By default, Laravel will use the command's name to generate the string key that is used to acquire the atomic lock in your application's cache. However, you may customize this key by defining an isolatableId method on your Artisan command class, allowing you to integrate the command's arguments or options into the key:

/**
 * Get the isolatable ID for the command.
 */
public function isolatableId(): string
{
    return $this->argument('user');
}

Lock Expiration Time

By default, isolation locks expire after the command is finished. Or, if the command is interrupted and unable to finish, the lock will expire after one hour. However, you may adjust the lock expiration time by defining a isolationLockExpiresAt method on your command:

use DateTimeInterface;
use DateInterval;
 
/**
 * Determine when an isolation lock expires for the command.
 */
public function isolationLockExpiresAt(): DateTimeInterface|DateInterval
{
    return now()->addMinutes(5);
}

Defining Input Expectations

When writing console commands, it is common to gather input from the user through arguments or options. Laravel makes it very convenient to define the input you expect from the user using the signature property on your commands. The signature property allows you to define the name, arguments, and options for the command in a single, expressive, route-like syntax.

Arguments

All user supplied arguments and options are wrapped in curly braces. In the following example, the command defines one required argument: user:

/**
 * The name and signature of the console command.
 *
 * @var string
 */
protected $signature = 'mail:send {user}';

You may also make arguments optional or define default values for arguments:

// Optional argument...
'mail:send {user?}'
 
// Optional argument with default value...
'mail:send {user=foo}'

Options

Options, like arguments, are another form of user input. Options are prefixed by two hyphens (--) when they are provided via the command line. There are two types of options: those that receive a value and those that don't. Options that don't receive a value serve as a boolean "switch". Let's take a look at an example of this type of option:

/**
 * The name and signature of the console command.
 *
 * @var string
 */
protected $signature = 'mail:send {user} {--queue}';

In this example, the --queue switch may be specified when calling the Artisan command. If the --queue switch is passed, the value of the option will be true. Otherwise, the value will be false:

php artisan mail:send 1 --queue

Options With Values

Next, let's take a look at an option that expects a value. If the user must specify a value for an option, you should suffix the option name with a = sign:

/**
 * The name and signature of the console command.
 *
 * @var string
 */
protected $signature = 'mail:send {user} {--queue=}';

In this example, the user may pass a value for the option like so. If the option is not specified when invoking the command, its value will be null:

php artisan mail:send 1 --queue=default

You may assign default values to options by specifying the default value after the option name. If no option value is passed by the user, the default value will be used:

'mail:send {user} {--queue=default}'

Option Shortcuts

To assign a shortcut when defining an option, you may specify it before the option name and use the | character as a delimiter to separate the shortcut from the full option name:

'mail:send {user} {--Q|queue}'

When invoking the command on your terminal, option shortcuts should be prefixed with a single hyphen and no = character should be included when specifying a value for the option:

php artisan mail:send 1 -Qdefault

Input Arrays

If you would like to define arguments or options to expect multiple input values, you may use the * character. First, let's take a look at an example that specifies such an argument:

'mail:send {user*}'

When calling this method, the user arguments may be passed in order to the command line. For example, the following command will set the value of user to an array with 1 and 2 as its values:

php artisan mail:send 1 2

This * character can be combined with an optional argument definition to allow zero or more instances of an argument:

'mail:send {user?*}'

Option Arrays

When defining an option that expects multiple input values, each option value passed to the command should be prefixed with the option name:

'mail:send {--id=*}'

Such a command may be invoked by passing multiple --id arguments:

php artisan mail:send --id=1 --id=2

Input Descriptions

You may assign descriptions to input arguments and options by separating the argument name from the description using a colon. If you need a little extra room to define your command, feel free to spread the definition across multiple lines:

/**
 * The name and signature of the console command.
 *
 * @var string
 */
protected $signature = 'mail:send
                        {user : The ID of the user}
                        {--queue : Whether the job should be queued}';

Prompting for Missing Input

If your command contains required arguments, the user will receive an error message when they are not provided. Alternatively, you may configure your command to automatically prompt the user when required arguments are missing by implementing the PromptsForMissingInput interface:

<?php
 
namespace App\Console\Commands;
 
use Illuminate\Console\Command;
use Illuminate\Contracts\Console\PromptsForMissingInput;
 
class SendEmails extends Command implements PromptsForMissingInput
{
    /**
     * The name and signature of the console command.
     *
     * @var string
     */
    protected $signature = 'mail:send {user}';
 
    // ...
}

If Laravel needs to gather a required argument from the user, it will automatically ask the user for the argument by intelligently phrasing the question using either the argument name or description. If you wish to customize the question used to gather the required argument, you may implement the promptForMissingArgumentsUsing method, returning an array of questions keyed by the argument names:

/**
 * Prompt for missing input arguments using the returned questions.
 *
 * @return array<string, string>
 */
protected function promptForMissingArgumentsUsing(): array
{
    return [
        'user' => 'Which user ID should receive the mail?',
    ];
}

You may also provide placeholder text by using a tuple containing the question and placeholder:

return [
    'user' => ['Which user ID should receive the mail?', 'E.g. 123'],
];

If you would like complete control over the prompt, you may provide a closure that should prompt the user and return their answer:

use App\Models\User;
use function Laravel\Prompts\search;
 
// ...
 
return [
    'user' => fn () => search(
        label: 'Search for a user:',
        placeholder: 'E.g. Taylor Otwell',
        options: fn ($value) => strlen($value) > 0
            ? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
            : []
    ),
];

If you wish to prompt the user to select or enter options, you may include prompts in your command's handle method. However, if you only wish to prompt the user when they have also been automatically prompted for missing arguments, then you may implement the afterPromptingForMissingArguments method:

use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use function Laravel\Prompts\confirm;
 
// ...
 
/**
 * Perform actions after the user was prompted for missing arguments.
 */
protected function afterPromptingForMissingArguments(InputInterface $input, OutputInterface $output): void
{
    $input->setOption('queue', confirm(
        label: 'Would you like to queue the mail?',
        default: $this->option('queue')
    ));
}

Command I/O

Retrieving Input

While your command is executing, you will likely need to access the values for the arguments and options accepted by your command. To do so, you may use the argument and option methods. If an argument or option does not exist, null will be returned:

/**
 * Execute the console command.
 */
public function handle(): void
{
    $userId = $this->argument('user');
}

If you need to retrieve all of the arguments as an array, call the arguments method:

$arguments = $this->arguments();

Options may be retrieved just as easily as arguments using the option method. To retrieve all of the options as an array, call the options method:

// Retrieve a specific option...
$queueName = $this->option('queue');
 
// Retrieve all options as an array...
$options = $this->options();

Prompting for Input

In addition to displaying output, you may also ask the user to provide input during the execution of your command. The ask method will prompt the user with the given question, accept their input, and then return the user's input back to your command:

/**
 * Execute the console command.
 */
public function handle(): void
{
    $name = $this->ask('What is your name?');
 
    // ...
}

The ask method also accepts an optional second argument which specifies the default value that should be returned if no user input is provided:

$name = $this->ask('What is your name?', 'Taylor');

The secret method is similar to ask, but the user's input will not be visible to them as they type in the console. This method is useful when asking for sensitive information such as passwords:

$password = $this->secret('What is the password?');

Asking for Confirmation

If you need to ask the user for a simple "yes or no" confirmation, you may use the confirm method. By default, this method will return false. However, if the user enters y or yes in response to the prompt, the method will return true.

if ($this->confirm('Do you wish to continue?')) {
    // ...
}

If necessary, you may specify that the confirmation prompt should return true by default by passing true as the second argument to the confirm method:

if ($this->confirm('Do you wish to continue?', true)) {
    // ...
}

Auto-Completion

The anticipate method can be used to provide auto-completion for possible choices. The user can still provide any answer, regardless of the auto-completion hints:

$name = $this->anticipate('What is your name?', ['Taylor', 'Dayle']);

Alternatively, you may pass a closure as the second argument to the anticipate method. The closure will be called each time the user types an input character. The closure should accept a string parameter containing the user's input so far, and return an array of options for auto-completion:

$name = $this->anticipate('What is your address?', function (string $input) {
    // Return auto-completion options...
});

Multiple Choice Questions

If you need to give the user a predefined set of choices when asking a question, you may use the choice method. You may set the array index of the default value to be returned if no option is chosen by passing the index as the third argument to the method:

$name = $this->choice(
    'What is your name?',
    ['Taylor', 'Dayle'],
    $defaultIndex
);

In addition, the choice method accepts optional fourth and fifth arguments for determining the maximum number of attempts to select a valid response and whether multiple selections are permitted:

$name = $this->choice(
    'What is your name?',
    ['Taylor', 'Dayle'],
    $defaultIndex,
    $maxAttempts = null,
    $allowMultipleSelections = false
);

Writing Output

To send output to the console, you may use the line, info, comment, question, warn, and error methods. Each of these methods will use appropriate ANSI colors for their purpose. For example, let's display some general information to the user. Typically, the info method will display in the console as green colored text:

/**
 * Execute the console command.
 */
public function handle(): void
{
    // ...
 
    $this->info('The command was successful!');
}

To display an error message, use the error method. Error message text is typically displayed in red:

$this->error('Something went wrong!');

You may use the line method to display plain, uncolored text:

$this->line('Display this on the screen');

You may use the newLine method to display a blank line:

// Write a single blank line...
$this->newLine();
 
// Write three blank lines...
$this->newLine(3);

Tables

The table method makes it easy to correctly format multiple rows / columns of data. All you need to do is provide the column names and the data for the table and Laravel will automatically calculate the appropriate width and height of the table for you:

use App\Models\User;
 
$this->table(
    ['Name', 'Email'],
    User::all(['name', 'email'])->toArray()
);

Progress Bars

For long running tasks, it can be helpful to show a progress bar that informs users how complete the task is. Using the withProgressBar method, Laravel will display a progress bar and advance its progress for each iteration over a given iterable value:

use App\Models\User;
 
$users = $this->withProgressBar(User::all(), function (User $user) {
    $this->performTask($user);
});

Sometimes, you may need more manual control over how a progress bar is advanced. First, define the total number of steps the process will iterate through. Then, advance the progress bar after processing each item:

$users = App\Models\User::all();
 
$bar = $this->output->createProgressBar(count($users));
 
$bar->start();
 
foreach ($users as $user) {
    $this->performTask($user);
 
    $bar->advance();
}
 
$bar->finish();

Registering Commands

By default, Laravel automatically registers all commands within the app/Console/Commands directory. However, you can instruct Laravel to scan other directories for Artisan commands using the withCommands method in your application's bootstrap/app.php file:

->withCommands([
    __DIR__.'/../app/Domain/Orders/Commands',
])

If necessary, you may also manually register commands by providing the command's class name to the withCommands method:

use App\Domain\Orders\Commands\SendEmails;
 
->withCommands([
    SendEmails::class,
])

When Artisan boots, all the commands in your application will be resolved by the service container and registered with Artisan.

Programmatically Executing Commands

Sometimes you may wish to execute an Artisan command outside of the CLI. For example, you may wish to execute an Artisan command from a route or controller. You may use the call method on the Artisan facade to accomplish this. The call method accepts either the command's signature name or class name as its first argument, and an array of command parameters as the second argument. The exit code will be returned:

use Illuminate\Support\Facades\Artisan;
 
Route::post('/user/{user}/mail', function (string $user) {
    $exitCode = Artisan::call('mail:send', [
        'user' => $user, '--queue' => 'default'
    ]);
 
    // ...
});

Alternatively, you may pass the entire Artisan command to the call method as a string:

Artisan::call('mail:send 1 --queue=default');

Passing Array Values

If your command defines an option that accepts an array, you may pass an array of values to that option:

use Illuminate\Support\Facades\Artisan;
 
Route::post('/mail', function () {
    $exitCode = Artisan::call('mail:send', [
        '--id' => [5, 13]
    ]);
});

Passing Boolean Values

If you need to specify the value of an option that does not accept string values, such as the --force flag on the migrate:refresh command, you should pass true or false as the value of the option:

$exitCode = Artisan::call('migrate:refresh', [
    '--force' => true,
]);

Queueing Artisan Commands

Using the queue method on the Artisan facade, you may even queue Artisan commands so they are processed in the background by your queue workers. Before using this method, make sure you have configured your queue and are running a queue listener:

use Illuminate\Support\Facades\Artisan;
 
Route::post('/user/{user}/mail', function (string $user) {
    Artisan::queue('mail:send', [
        'user' => $user, '--queue' => 'default'
    ]);
 
    // ...
});

Using the onConnection and onQueue methods, you may specify the connection or queue the Artisan command should be dispatched to:

Artisan::queue('mail:send', [
    'user' => 1, '--queue' => 'default'
])->onConnection('redis')->onQueue('commands');

Calling Commands From Other Commands

Sometimes you may wish to call other commands from an existing Artisan command. You may do so using the call method. This call method accepts the command name and an array of command arguments / options:

/**
 * Execute the console command.
 */
public function handle(): void
{
    $this->call('mail:send', [
        'user' => 1, '--queue' => 'default'
    ]);
 
    // ...
}

If you would like to call another console command and suppress all of its output, you may use the callSilently method. The callSilently method has the same signature as the call method:

$this->callSilently('mail:send', [
    'user' => 1, '--queue' => 'default'
]);

Signal Handling

As you may know, operating systems allow signals to be sent to running processes. For example, the SIGTERM signal is how operating systems ask a program to terminate. If you wish to listen for signals in your Artisan console commands and execute code when they occur, you may use the trap method:

/**
 * Execute the console command.
 */
public function handle(): void
{
    $this->trap(SIGTERM, fn () => $this->shouldKeepRunning = false);
 
    while ($this->shouldKeepRunning) {
        // ...
    }
}

To listen for multiple signals at once, you may provide an array of signals to the trap method:

$this->trap([SIGTERM, SIGQUIT], function (int $signal) {
    $this->shouldKeepRunning = false;
 
    dump($signal); // SIGTERM / SIGQUIT
});

Stub Customization

The Artisan console's make commands are used to create a variety of classes, such as controllers, jobs, migrations, and tests. These classes are generated using "stub" files that are populated with values based on your input. However, you may want to make small changes to files generated by Artisan. To accomplish this, you may use the stub:publish command to publish the most common stubs to your application so that you can customize them:

php artisan stub:publish

The published stubs will be located within a stubs directory in the root of your application. Any changes you make to these stubs will be reflected when you generate their corresponding classes using Artisan's make commands.

Events

Artisan dispatches three events when running commands: Illuminate\Console\Events\ArtisanStarting, Illuminate\Console\Events\CommandStarting, and Illuminate\Console\Events\CommandFinished. The ArtisanStarting event is dispatched immediately when Artisan starts running. Next, the CommandStarting event is dispatched immediately before a command runs. Finally, the CommandFinished event is dispatched once a command finishes executing.