Artisan 命令行
Artisan 命令行
Artisan 命令行
簡介
Artisan 是 Laravel 自帶的命令行接口，他提供了許多使用的命令來幫助你構建 Laravel 應用 。要查看所有可用的 Artisan 命令的列表，可以使用 list 命令：
php artisan list
每個命令都包含了「幫助」 界面 ，它會顯示和概述命令的可用參數(shù)及選項。只需要在命令前加上 help 即可查看命令幫助界面 ：
php artisan help migrate
Tinker 命令 (REPL)
所有 Laravel 應用都包含了 Tinker，一個基于 PsySH 包提供支持的 REPL 。Tinker 讓你可以在命令行中與你整個的 Laravel 應用進行交互 。 包括 Eloquent ORM、任務、事件等等。運行 Artisan 命令 tinker 進入 Tinker 環(huán)境：
php artisan tinker
你可以通過使用 vendor:publish 命令發(fā)布 Tinker 配置文件：
php artisan vendor:publish --provider="Laravel\Tinker\TinkerServiceProvider"
命令白名單
Tinker 通過采用白名單的方式來確定允許哪些 Artisan 命令可以在 shell 中運行。默認情況下，你可以運行 clear-compiled 、down、env、 inspire、migrate、 optimize、和 up 命令。如果你想要添加更多的白名單命令，可以將它們添加到 tinker.php 配置文件中的 commands 數(shù)組里：
'commands' => [ // App\Console\Commands\ExampleCommand::class, ],
黑名單別名
通常，Tinker 會在 Tinker 中根據(jù)你的需要自動為類添加別名。然而，你可能不希望為某些類添加別名。你可以在 tinker.php 配置文件中的 dont_alias 數(shù)組里列舉這些類來完成此操作：
'dont_alias' => [ App\User::class, ],
編寫命令
除 Artisan 提供的命令外，你還可以構建自己的自定義命令。 命令通常存儲在 app/Console/Commands 目錄中；不過，只要你的命令可以由 Composer 加載，你就可以自由選擇自己的存儲位置。
生成命令
要創(chuàng)建一個新的命令，可以使用 Artisan 命令 make:command。這個命令會在 app/Console/Commands 目錄中創(chuàng)建一個新的命令類。 不必擔心應用中不存在這個目錄，因為它會在你第一次運行 Artisan 命令 make:command 時創(chuàng)建。生成的命令會包括所有命令中默認存在的屬性和方法：
php artisan make:command SendEmails
命令結構
命令運行后，你應該先填寫 signature 和 description 屬性以便你在輸入 php artisan list 時能夠清楚知道用法。執(zhí)行命令時會調用 handle 方法，你可以在這個方法中放置命令邏輯。
{tip} 為了代碼更好的復用，最好保持你的控制臺代碼輕量并且能夠延遲到應用服務中完成。在下面的例子中，我們將注入一個服務類來完成發(fā)送郵件的重任。
來看一個簡單的例子。我們可以在 handle 方法中注入我們需要的任何依賴項。 Laravel 服務容器 將會自動注入所有在構造函數(shù)中帶類型約束的依賴:
<?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
*/
protected $signature = 'email:send {user}';
/**
* The console command description.
*
* @var string
*/
protected $description = 'Send drip e-mails to a user';
/**
* Create a new command instance.
*
* @return void
*/
public function __construct() {
parent::__construct();
}
/**
* Execute the console command.
*
* @param \App\DripEmailer $drip
* @return mixed
*/
public function handle(DripEmailer $drip)
{
$drip->send(User::find($this->argument('user')));
}
}閉包命令
基于閉包的命令提供了一個用類代替定義控制臺命令的方法。同理，閉包路由是控制器的一種替代方法，而閉包命令則可以認為是命令類的替代方法。在 app/Console/Kernel.php 文件的 commands 方法中，Laravel 加載了 routes/console.php file:
/**
* Register the Closure based commands for the application.
*
* @return void
*/
protected function commands(){
require base_path('routes/console.php');
}雖然這個文件沒有定義 HTTP 路由，但是它將基于控制臺的入口點（路由）定義到了應用中。在這個文件，你可以使用 Artisan::command 方法定義所有的閉包路由。 command 方法接受兩個參數(shù): 命令名稱 和一個接受命令參數(shù)及選項的閉包:
Artisan::command('build {project}', function ($project) {
$this->info("Building {$project}!");
});閉包綁定底層的命令實例，因為你可以訪問所有能夠在完整命令類中的所有輔助方法。
類型提示依賴
除了接收命令的參數(shù)和選項外，命令閉包也可以使用類型提示從 服務容器 中解析其他的依賴關系:
use App\User;
use App\DripEmailer;Artisan::command('email:send {user}', function (DripEmailer $drip, $user) {
$drip->send(User::find($user));
});閉包命令描述
當你定義一個閉包命令，你應當使用 describe 方法來為命令添加描述。這個描述會在你運行 php artisan list 或者 php artisan help 命令時顯示:
Artisan::command('build {project}', function ($project) {
$this->info("Building {$project}!");
})->describe('Build the project');定義輸出期望
在編寫控制臺命令時，通常是通過參數(shù)和選項來收集用戶輸入的。Laravel 可以通過 signature 屬性非常方便的定義你期望用戶輸入的內容。signature 允許使用單一且可讀性高，類似路由的語法定義命令的名稱、參數(shù)和選項。
參數(shù)
所有用戶提供的參數(shù)及選項都被包含在花括號中。在下面的例子中，這個命令定義了一個 必須的參數(shù): user:
/**
* The name and signature of the console command.
*
* @var string
*/
protected $signature = 'email:send {user}';你也可以創(chuàng)建可選參數(shù)，并定義參數(shù)的默認值:
// 可選參數(shù)...
email:send {user?}
// 帶有默認值的可選參數(shù)...
email:send {user=foo}選項
選項，類似于參數(shù)，是用戶輸入的另一種格式。當命令行指定選項時，它們以兩個連字符 ( -- ) 作為前綴。有兩種類型的選項：接收值和不接收值。不接收值的選項就像是一個布爾值的「開關」。讓我們看一下這種類型的選項的例子：
/**
* 命令行的名稱及簽名。
*
* @var string
*/
protected $signature = 'email:send {user} {--queue}';在這個例子中，可以在調用 Artisan 命令時指定 --queue 開關。如果 --queue 開關被傳遞，該選項的值為 true， 否則為 false ：
php artisan email:send 1 --queue
帶值的選項
接下來，讓我們來看一個帶值的選項。如果想讓用戶必須為選項指定一個值，則需要在選項名稱末尾追加一個等號 = 作為的后綴：
/**
* 命令行的名稱及簽名。
*
* @var string
*/
protected $signature = 'email:send {user} {--queue=}';在這個例子中， 用戶可以傳遞該選項的值，如下所示：
php artisan email:send 1 --queue=default
你也可以通過在選項名稱后面指定默認值來設定該選項的默認值。如果用戶沒有傳遞選項值，將使用設定的默認值：
email:send {user} {--queue=default}選項簡寫
要在定義選項時指定簡寫，你可以在選項名稱前指定它，并用 | 分隔符將簡寫與完整選項名稱分隔開：
email:send {user} {--Q|queue}輸入數(shù)組
如果你想定義接收數(shù)組輸入的參數(shù)或選項，你可以使用 * 符號。首先，我們先看一個數(shù)組參數(shù)的實例：
email:send {user*}調用此方法時，該 user 參數(shù)的輸入?yún)?shù)可按順序傳遞給命令行。例如，以下命令會設置 user 的值為 ['foo', 'bar'] ：
php artisan email:send foo bar
當定義接收數(shù)組的選項時，傳遞給命令行的每個選項值都應以選項名稱為前綴：
email:send {user} {--id=*}
php artisan email:send --id=1 --id=2輸入說明
你可以通過使用冒號來為參數(shù)和選項添加說明，并使其將他們隔開。如果你需要一點額外的空間來定義你的命令，可以隨意分開在多個行里：
/**
* 命令行的名稱及簽名。
*
* @var string
*/
protected $signature = 'email:send
{user : The ID of the user}
{--queue= : Whether the job should be queued}';Command I/O
獲取輸入
在命令執(zhí)行時，顯然你需要獲取命令接收到的參數(shù)和選項的值。你可以用 argument 和 option 方法來達到目的：
/**
* 執(zhí)行命令。
*
* @return mixed
*/
public function handle(){
$userId = $this->argument('user');
//
}如果你想所有的參數(shù)以 array 數(shù)組獲取，可以調用 arguments 方法：
$arguments = $this->arguments();
和獲取參數(shù)類似，option 方法可以非常容易的獲取選項的值。要將所有的選項以數(shù)組獲取，使用 options 方法：
// 獲取一個指定的選項值
$queueName = $this->option('queue');
// 獲取所有的選項值
$options = $this->options();如果參數(shù)或選項不存在，則返回 null 。
交互式輸入
除了顯示輸出外，你還可以要求用戶在命令執(zhí)行時提供輸入。 ask 方法將提示用戶輸入并接收，然后用戶的輸入將會傳入你的命令：
/**
* 執(zhí)行命令。
*
* @return mixed
*/
public function handle(){
$name = $this->ask('What is your name?');
}secret 方法和 ask 方法類似，但當用戶在控制臺輸入時他們的輸入內容是不可見的。這個方法適用于需要用戶輸入像密碼這樣的敏感信息的時候：
$password = $this->secret('What is the password?');請求確認
如果你想要尋求用戶確認一些簡單的信息，你可以使用 confirm 方法。默認情況下，該方法將返回 false 。但如果用戶在回復中輸入 y 或者 yes 則會返回 true 。
if ($this->confirm('Do you wish to continue?')) {
//
}自動補全
anticipate 方法可用于為可能的選擇提供自動補全功能。用戶仍然可以忽略自動補全的提示，作任意回答：
$name = $this->anticipate('What is your name?', ['Taylor', 'Dayle']);多重選擇
如果你要給用戶提供一些預設的選擇，可以使用 choice 方法。你也可以設置默認值的索引，用以應對用戶沒有選擇的情景：
$name = $this->choice('What is your name?', ['Taylor', 'Dayle'], $defaultIndex);編寫輸出
可以使用 line 、 info 、 comment 、 question 和 error 方法來將輸出發(fā)送到終端。每個方法都使用適當?shù)?nbsp;ANSI 顏色表明其目的。例如，讓我們向用戶顯示一些普通信息，通常來說，最好使用 info 方法，它會在控制臺將輸出的內容顯示為綠色：
/**
* 執(zhí)行命令。
*
* @return mixed
*/
public function handle(){
$this->info('Display this on the screen');
}顯示錯誤信息， 使用 error 方法。 錯誤信息則會顯示為紅色：
$this->error('Something went wrong!');如果你想在控制臺顯示無顏色設置的輸出，請使用 line 方法：
$this->line('Display this on the screen');表格布局
對于多行列數(shù)據(jù)的格式化輸出，table 方法處理起來更輕松。基于傳入的表頭和行數(shù)據(jù)，它會動態(tài)計算寬高：
$headers = ['Name', 'Email']; $users = App\User::all(['name', 'email'])->toArray(); $this->table($headers, $users);
進度條
對于耗時任務，提示進度非常有必要。使用 output 對象就可以創(chuàng)建、加載以及停止進度條。首先，定義好任務總步數(shù)，然后，在每次任務執(zhí)行時加載進度條：
$users = App\User::all();
$bar = $this->output->createProgressBar(count($users));
$bar->start();foreach ($users as $user) {
$this->performTask($user);
$bar->advance();
}$bar->finish();參閱 Symfony Progress Bar component documentation 獲取更多高級用法。
注冊命令
app/Console/Commands 目錄下的命令都會被注冊，這是由于控制臺內核的 commands 方法調用了 load。實際上，可隨意調用 load 來掃描其他目錄下的 Artisan 命令：
/**
* 注冊應用的命令
*
* @return void
*/
protected function commands(){
$this->load(__DIR__.'/Commands');
$this->load(__DIR__.'/MoreCommands');
// ...
}也可以在 app/Console/Kernel.php 文件的 $commands 屬性中手動注冊命令的類名。Artisan 啟動時，這個屬性列出的命令都將由 服務容器 解析并通過 Artisan 進行注冊：
protected $commands = [ Commands\SendEmails::class ];
程序調用命令
有時需要在 CLI 之外執(zhí)行 Artisan 命令，例如，在路由或控制器里觸發(fā) Artisan 命令。要實現(xiàn)調用，可以使用 Artisan 門面的 call 方法。call 方法的第一個參數(shù)接受命令名，第二個參數(shù)接受數(shù)組形式的命令參數(shù)。退出碼將返回：
Route::get('/foo', function () {
$exitCode = Artisan::call('email:send', [
'user' => 1,
'--queue' => 'default'
]);
//
});另外，你可以將整個 Artisan 命令作為字符串傳遞給 call 方法：
Artisan::call('email:send 1 --queue=default');Artisan 門面的 queue 方法可以將 Artisan 命令隊列化，交由 隊列工作進程 進行后臺處理。使用此方法之前，務必配置好隊列以及運行隊列監(jiān)聽器：
Route::get('/foo', function () {
Artisan::queue('email:send', [
'user' => 1,
'--queue' => 'default'
]);
//
});你也可以指定 Artisan 命令派發(fā)的連接或任務：
Artisan::queue('email:send', [
'user' => 1,
'--queue' => 'default'
])->onConnection('redis')->onQueue('commands');傳遞數(shù)組值
如果定義了接受數(shù)組的選項，可以直接傳遞數(shù)組到該選項：
Route::get('/foo', function () {
$exitCode = Artisan::call('email:send', [
'user' => 1,
'--id' => [5, 13]
]);
});傳遞布爾值
需要指定沒有選項值的選項時，例如，migrate:refresh 命令的 --force 選項，就可以傳入 true 或 false：
$exitCode = Artisan::call('migrate:refresh', [
'--force' => true,
]);命令的互相調用
call 方法可以實現(xiàn)調用其它 Artisan 命令。call 方法接受命令名和數(shù)組形式的選項：
/**
* 執(zhí)行控制臺命令
*
* @return mixed
*/
public function handle(){
$this->call('email:send', [
'user' => 1,
'--queue' => 'default'
]);
//
}如果要抑制控制臺命令的所有輸出，可以使用 callSilent 方法。callSilent 的使用方法同 call ：
$this->callSilent('email:send', [
'user' => 1,
'--queue' => 'default'
]);