Artisan Console
1. Introduction
Artisan is the command line interface provided by Laravel, which provides us with many useful commands in the development process. To view all available Artisan commands, use the list
Command:
php artisan list
Each command can be used help
The command displays the command description and command parameters and options. To view the help interface, just add help
You can:
php artisan help migrate
Laravel REPL
All Larravel applications provide Tinker, a PsySH The expansion pack driven REPL (Read Eval Print Loop, that is, the terminal command line "read evaluate output" cycle tool). Tinker allows you to interact with the entire Laravel application through the command line, including Eloquent ORM, tasks, events, and so on. To enter the Tinker environment, run tinker
Command:
php artisan tinker
2. Write Command
In addition to the system commands provided by Artisan, you can also write your own commands. Custom commands are usually stored in app/Console/Commands
Directory; Of course, you can also choose your own storage location, as long as the command class can be automatically loaded by Composer.
Generate Command
To create a new command, you can use the Artisan command make:command
, the command will app/Console/Commands
Create a new command class under the directory. If the directory does not exist, don't worry, it will run Artisan command for the first time make:command
Is created when. The generated command will contain default property settings and methods common to all commands:
php artisan make:command SendEmails
Next, before this command can be executed through Artisan CLI Register this command 。
Command structure
After the command is generated, you need to fill in the signature
and description
Property. These two properties are called list
It will be used when displaying commands. handle
Method is called when the command is executed. You can put all the command logic in this method.
Note: In order to better realize code reuse, the best practice is to keep the console commands lightweight and let them delay to the application service to complete the task. In the following example, we have injected a service class to complete such "heavy" tasks as sending emails.
Let's take a look at an example. Note that we can inject any dependency into the constructor of the command class Service Container All dependent type prompts will be automatically injected into the constructor:
<? php namespace App\Console\Commands; use App\User; use App\DripEmailer; use Illuminate\Console\Command; class SendEmails extends Command { /** * The name and signature of the console command. * * @var string * @translator laravelacademy.org */ protected $signature = 'email:send {user}'; /** * The console command description. * * @var string */ protected $description = 'Send drip e-mails to a user'; /** * The drip e-mail service. * * @var DripEmailer */ protected $drip; /** * Create a new command instance. * * @param DripEmailer $drip * @return void */ public function __construct(DripEmailer $drip) { parent::__construct(); $this->drip = $drip; } /** * Execute the console command. * * @return mixed */ public function handle() { $this->drip->send(User::find($this->argument('user'))); } }
Closure command
Closure based commands, like closure routing for controllers, provide an optional solution for defining console commands in a class way app/Console/Kernel.php
Filed commands
Method, Larravel loads the routes/console.php
File:
/** *Register closure based commands for applications * * @return void */ protected function commands() { require base_path('routes/console.php'); }
Although this file does not define HTTP routing, it defines the console based application portal (the same as routing). In this file, you can use Artisan::command
Method defines all closure based routes. command
Method receives two parameters—— Command ID And closures that receive command parameters and options:
Artisan::command('build {project}', function ($project) { $this->info("Building {$project}!"); });
This closure is bound to the underlying command instance, so you can access all auxiliary methods as in the complete command class.
Type hint dependency
In addition to receiving command parameters and options, closure commands can also type prompts Service Container Additional dependencies for external resolution:
use App\User; use App\DripEmailer; Artisan::command('email:send {user}', function (DripEmailer $drip, $user) { $drip->send(User::find($user)); });
Closure Command Description
When defining closure based commands, you can use the describe
Method to add a command description, which will be run php artisan list
or php artisan help
When command:
Artisan::command('build {project}', function ($project) { $this->info("Building {$project}!"); })->describe('Build the project');
3. Define expected input
When writing console commands, user input is usually collected through parameters and options. Laravel makes this operation convenient: use in commands signature
Property to define the user input we expect. signature
Properties allow you to define command names, parameters, and options through an elegant, routing style syntax.
parameter
All parameters and options provided by the user are enclosed in braces. The command defined in the following example requires user input Mandatory parameter user
:
/** *Console Command Name * * @var string */ protected $signature = 'email:send {user}';
You can also make this parameter optional and define the default optional parameter values:
//Option Parameters email:send {user?} //Option parameters with default values email:send {user=foo}
option
Options, like parameters, are another form of user input. The difference is that options are preceded by two dashes( --
), there are two types of options: receive value and do not receive value. Options that do not receive values are typically used as Boolean switches. Let's look at an option of this type:
/** *Console Command Name * * @var string */ protected $signature = 'email:send {user} {--queue}';
In this example, --queue
The switch is specified when the Artisan command is called. If --queue
The switch is passed with a value of true
, otherwise its value is false
:
php artisan email:send 1 --queue
Options with values
Next, let's look at an option with a value. If the user must specify a value for the option, you need to use the =
To assign:
/** *Console Command Name * * @var string */ protected $signature = 'email:send {user} {--queue=}';
In this example, the user can pass values in this way:
php artisan email:send 1 --queue=default
You can also assign a default value to an option. If the user does not pass a value to an option, the default value will be used:
email:send {user} {--queue=default}
Option Abbreviation
If you want to assign a abbreviation to a command option, you can specify and use a separator before the option |
Separate shorthand and full option names:
email:send {user} {--Q|queue}
Input array
If you want to define parameters and options to specify the input array, you can use characters *
First, let's look at an example of specifying array parameters:
email:send {user*}
When this method is called, user
Parameters will be passed to the command line in sequence. For example, the following command will set user
The value of is ['foo', 'bar']
:
php artisan email:send foo bar
When defining an option of the expected input array, each option value passed to the command should be prefixed with the option name:
email:send {user} {--id=*} php artisan email:send --id=1 --id=2
Enter Description
You can assign descriptions to input parameters and options by separating parameters and descriptions with colons. If you need some space to define commands, you can define commands by wrapping lines:
/** *Console Command Name * * @var string * @translator laravelacademy.org */ protected $signature = 'email:send {user : The ID of the user} {--queue= : Whether the job should be queued}';
4. Command I/O
Get input
When the command is executed, it is obvious that you need to access the parameters and option values obtained by the command. use argument
and option
The method can achieve:
/** *Execute the console command * * @return mixed */ public function handle() { $userId = $this->argument('user'); // }
If you need to return the values of all parameters in an array, call arguments
method:
$arguments = $this->arguments();
The option value is as simple as the parameter value option
Method. To return all option values in an array, call options
method:
//Get Specified Options $queueName = $this->option('queue'); //Get All Options $options = $this->options();
If the parameter or option does not exist, return null
。
Input prompt
In addition to displaying the output, you may also want the user to provide input during command execution. ask
The method will prompt the user with the given question, receive input, and then return to the command entered by the user:
/** *Execute console commands * * @return mixed */ public function handle(){ $name = $this->ask('What is your name?'); }
secret
Methods and ask
The method is similar, but user input is invisible to them at the terminal. This method is useful when asking users for some sensitive information, such as passwords:
$password = $this->secret('What is the password?');
Let the user confirm
If you need the user to confirm the information, you can use confirm
Method. By default, this method returns false
, if the user enters y
, the method returns true
:
if ($this->confirm('Do you wish to continue? [y|N]')) { // }
AutoComplete
anticipate
The method can be used to provide automatic completion for possible options, and the user can still select the answer regardless of these choices:
$name = $this->anticipate('What is your name?', ['Taylor', 'Dayle']);
Provide users with choices
If you need to give users predefined choices, you can use choice
method. The user selects the index of the answer, but the answer value is returned to you. If the user does not select anything, you can set the default return value:
$name = $this->choice('What is your name?', ['Taylor', 'Dayle'], false);
Write Output
To send output to the console, use the line
, info
, comment
, question
and error
Method, each method will be identified with the corresponding ANSI color. For example, to display an information message to the user, use info
The method is displayed in green on the terminal:
/** *Execute console commands * * @return mixed */ public function handle(){ $this->info('Display this on the screen'); }
To display an error message, use the error
method. The error message text is usually red:
$this->error('Something went wrong!');
If you want to display native output, you can use line
Method, which outputs characters without color:
$this->line('Display this on the screen');
Table Layout
table
The method makes it easy to output data in multi row/column format. You only need to pass the header and row to the method. The width and height will be automatically calculated based on the given data:
$headers = ['Name', 'Email']; $users = App\User::all(['name', 'email'])->toArray(); $this->table($headers, $users);
progress bar
For tasks that need to run for a long time, it is useful to display the progress indicator. Using this output object, we can start, advance, and stop the progress bar. At the beginning of the progress, you must define the number of steps, and then advance one grid for each step of the progress bar:
$users = App\User::all(); $bar = $this->output->createProgressBar(count($users)); foreach ($users as $user) { $this->performTask($user); $bar->advance(); } $bar->finish();
To learn more, see Symfony Progress Bar Component Document 。
4. Registration command
After the command is written, you need to register with Artisan before you can use it. This can be done in app/Console/Kernel.php
File. In this file, you will commands
You can see a command list in the property. To register your command, just add it to the list. When Artisan starts, the commands listed in this attribute will be parsed by the service container and registered through Artisan:
protected $commands = [ Commands\SendEmails::class ];
5. Calling commands through code
Sometimes you may want to execute Artisan commands outside the CLI. For example, you may want to trigger Artisan commands in the route or controller. You can use Artisan
On the facade call
Method to complete this function. call
The method receives the name of the executed command as the first parameter, the command parameter array as the second parameter, and the exit code is returned:
Route::get('/foo', function () { $exitCode = Artisan::call('email:send', [ 'user' => 1, '--queue' => 'default' ]); });
use Artisan
On the facade queue
Method, you can even put Artisan commands into the queue, so that they can be processed by queue workers in the background. Before using this method, make sure you have configured the queue and run the queue listener:
Route::get('/foo', function () { Artisan::queue('email:send', [ 'user' => 1, '--queue' => 'default' ]); });
If you need to specify the option value of not receiving strings, for example migrate:refresh
On command --force
Identification, Boolean value can be passed true
or false
:
$exitCode = Artisan::call('migrate:refresh', [ '--force' => true, ]);
Invoking commands through other commands
Sometimes you want to call other commands from an existing Artisan command. You can use call
Method development achieves this goal. call
Method receives command name and command parameters in array form:
/** *Execute console commands * * @return mixed */ public function handle(){ $this->call('email:send', [ 'user' => 1, '--queue' => 'default' ]); }
If you want to invoke other console commands and block all their output, you can use callSilent
method. callSilent
Methods and call
The method and usage are consistent:
$this->callSilent('email:send', [ 'user' => 1, '--queue' => 'default' ]);