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
Note:
Looking for hot reloading, multiline code editing, and autocompletion when interacting with your Laravel application? Check out Tinkerwell!
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"
Warning!
Thedispatchhelper function anddispatchmethod on theDispatchableclass depends on garbage collection to place the job on the queue. Therefore, when using tinker, you should useBus::dispatchorQueue::pushto dispatch jobs.
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, optimize, and
up 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')));
}
}
Note:
For greater code reuse, it is good practice to keep your console commands light and let them defer to application services to accomplish their tasks. In the example above, note that we inject a service class to do the "heavy lifting" of sending the e-mails.
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.
Within the commands method of your
app/Console/Kernel.php file, Laravel loads
the routes/console.php file:
/**
* Register the closure based commands for the application.
*/
protected function commands(): void
{
require base_path('routes/console.php');
}
Even though this 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
Warning!
To utilize this feature, your application must be using thememcached,redis,dynamodb,database,file, orarraycache driver as your application's default cache driver. In addition, all servers must be communicating with the same central cache server.
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
*/
protected function promptForMissingArgumentsUsing()
{
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()
: []
),
];
Note:
The comprehensive Laravel Prompts documentation includes additional information on the available prompts and their usage.
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.
*
* @param \Symfony\Component\Console\Input\InputInterface $input
* @param \Symfony\Component\Console\Output\OutputInterface $output
* @return void
*/
protected function afterPromptingForMissingArguments(InputInterface $input, OutputInterface $output)
{
$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
Note:
Laravel Prompts is a PHP package for adding beautiful and user-friendly forms to your command-line applications, with browser-like features including placeholder text and validation.
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();
Note:
For more advanced options, check out the Symfony Progress Bar component documentation.
Registering Commands
All of your console commands are registered within your
application's App\Console\Kernel class,
which is your application's "console kernel".
Within the commands method of this class,
you will see a call to the kernel's load
method. The load method will scan the
app/Console/Commands directory and
automatically register each command it contains with
Artisan. You are even free to make additional calls to
the load method to scan other directories
for Artisan commands:
/**
* Register the commands for the application.
*/
protected function commands(): void
{
$this->load(__DIR__.'/Commands');
$this->load(__DIR__.'/../Domain/Orders/Commands');
// ...
}
If necessary, you may manually register commands by
adding the command's class name to a
$commands property within your
App\Console\Kernel class. If this property
is not already defined on your kernel, you should define
it manually. When Artisan boots, all the commands listed
in this property will be resolved by the service container and
registered with Artisan:
protected $commands = [
Commands\SendEmails::class
];
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.