[ Laravel 5.2 文檔 ] 服務 -- Artisan Console

1、簡介

Artisan是 Laravel內建的命令列介面名稱，它為我們在開發過程中提供了很多有用的命令。通過強大的 SymfonyConsole 組件驅動。想要查看所有可用的Artisan命令，可使用 list命令：

php artisan list

每個命令都可以用 help指令顯示命令描述及命令參數和選項。想要查看協助介面，只需要在命令前加上 help就可以了：

php artisan help migrate

2、編寫命令

除了Artisan提供的命令之外，還可以構建自己的命令。你可以將自訂命令存放在 app/Console/Commands目錄；當然，你可以自己選擇存放位置，只要該命令可以被 composer.json自動載入即可。

要建立一個新命令，你可以使用Artisan命令 make:console：

php artisan make:console SendEmails

上述命令將會產生一個類 app/Console/Commands/SendEmails.php，當建立命令時， --command選項可用於分配終端命令名（在終端調用命令時用）：

php artisan make:console SendEmails --command=emails:send

命令結構

命令產生以後，需要填寫該類的 signature和 description屬性，這兩個屬性在調用 list顯示命令的時候會被用到。

handle方法在命令執行時被調用，你可以將所有命令邏輯都放在這個方法裡面，讓我們先看一個命令例子。

我們可以在命令控制器的建構函式中注入任何依賴，Laravel服務提供者將會在建構函式中自動注入所有依賴類型提示。要增強代碼的複用性，保持代碼輕量級並讓它們延遲到應用服務中完成任務是個不錯的實踐：

drip = $drip;    }    /**     * 執行控制台命令     *     * @return mixed     */    public function handle()    {        $this->drip->send(User::find($this->argument('user')));    }}

3、命令I/O

3.1 定義期望輸入

編寫控制台命令的時候，通常通過參數和選項收集使用者輸入，Laravel使這項操作變得很方便：在命令中使用 signature屬性來定義我們期望的使用者輸入。 signature屬性通過一個優雅的、路由風格的文法允許你定義命令的名稱、參數以及選項。所有使用者提供的參數和選項都包含在大括弧裡，下面這個例子定義的命令要求使用者輸入必選參數user：

/** * 控制台命令名稱 * * @var string */protected $signature = 'email:send {user}';

你還可以讓該參數可選可不選，以及定義預設的選擇性參數值：

// 選項參數...email:send {user?}// 帶預設值的選項參數...email:send {user=foo}

選項，和參數一樣，也是使用者輸入的一種格式，不同之處在於選項前面有兩個短劃線（–），我們可以這樣定義選項：

/** * 控制台命令名稱 * * @var string */protected $signature = 'email:send {user} {--queue}';

在本例中， --queue開關在調用Artisan命令的時候被指定。如果 --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}

如果你想要定義參數和選項以便指定輸入數組，可以使用字元*：

email:send {user*}email:send {user} {--id=*}

輸入描述

你可以通過冒號將參數和描述進行分隔的方式分配描述到輸入參數和選項：

/** * 控制台命令名稱 * * @var string */protected $signature = 'email:send    {user : The ID of the user}    {--queue= : Whether the job should be queued}';

3.2 擷取輸入

在命令被執行的時候，很明顯，你需要訪問命令擷取的參數和選項的值。使用 argument和 option方法即可實現：

要擷取參數的值，通過 argument方法：

/** * 執行控制台命令 * * @return mixed */public function handle(){    $userId = $this->argument('user');}

如果你需要以數組形式擷取所有參數值，使用不帶參數的 argument：

$arguments = $this->argument();

選項值和參數值的擷取一樣簡單，使用 option方法，同 argument一樣如果要擷取所有選項值，可以調用不帶參數的 option方法：

// 擷取指定選項...$queueName = $this->option('queue');// 擷取所有選項...$options = $this->option();

如果參數或選項不存在，返回null。

3.3 輸入提示

除了顯示輸出之外，你可能還要在命令執行期間要使用者提供輸入。 ask方法將會使用給定問題提示使用者，接收輸入，然後返回使用者輸入到命令：

/** * 執行控制台命令 * * @return mixed */public function handle(){    $name = $this->ask('What is your name?');}

secret方法和 ask方法類似，但使用者輸入在終端對他們而言是不可見的，這個方法在問使用者一些敏感資訊如密碼時很有用：

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

讓使用者確認

如果你需要讓使用者確認資訊，可以使用 confirm方法，預設情況下，該方法返回 false，如果使用者輸入 y，則該方法返回 true：

if ($this->confirm('Do you wish to continue? [y|N]')) {    //}

給使用者提供選擇

anticipate方法可用於為可能的選項提供自動完成功能，使用者仍然可以選擇答案，而不管這些選擇：

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

如果你需要給使用者預定義的選擇，可以使用 choice方法。使用者選擇答案的索引，但是返回給你的是答案的值。如果使用者什麼都沒選的話你可以設定預設返回的值：

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

3.4 編寫輸出

要將輸出發送到控制台，使用line, info, comment, question和 error方法，每個方法都會使用相應的ANSI顏色以作標識。

要顯示一條資訊訊息給使用者，使用 info方法。通常，在終端顯示為綠色：

/** * 執行控制台命令 * * @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');

表格版面配置

table方法使輸出多行/列格式的資料變得簡單，只需要將頭和行傳遞給該方法，寬度和高度將基於給定資料自動計算：

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

進度條

對需要較長時間啟動並執行任務，顯示進度列指示器很有用，使用該輸出對象，我們可以開始、前進以及停止該進度條。在開始進度時你必須定義步數，然後每走一步進度條前進一格：

$users = App\User::all();$this->output->progressStart(count($users));foreach ($users as $user) {    $this->performTask($user);    $this->output->progressAdvance();}$this->output->progressFinish();

想要瞭解更多，查看 Symfony進度條組件文檔。

4、註冊命令

命令編寫完成後，需要註冊到Artisan才可以使用，這可以在 app/Console/Kernel.php檔案中完成。

在該檔案中，你會在 commands屬性中看到一個命令列表，要註冊你的命令，只需將其加到該列表中即可。當Artisan啟動的時候，該屬性中列出的命令將會被服務容器解析被註冊到Artisan：

protected $commands = [    'App\Console\Commands\SendEmails'];

5、通過代碼調用命令

有時候你可能希望在CLI之外執行Artisan命令，比如，你可能希望在路由或控制器中觸發Artisan命令，你可以使用Artisan門面上的 call方法來完成這個。 call方法接收被執行的命令名稱作為第一個參數，命令參數數組作為第二個參數，結束代碼被返回：

Route::get('/foo', function () {    $exitCode = Artisan::call('email:send', [        'user' => 1, '--queue' => 'default'    ]);});

使用Artisan上的 queue方法，你甚至可以將Artisan命令放到隊列中，這樣它們就可以通過背景隊列工作者來處理：

Route::get('/foo', function () {    Artisan::queue('email:send', [        'user' => 1, '--queue' => 'default'    ]);});

如果你需要指定不接收字串的選項值，例如 migrate:refresh命令上的 --force標識，可以傳遞布爾值 true或 false：

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

通過其他命令調用命令

有時候你希望從一個已存在的Artisan命令中調用其它命令。你可以通過使用 call方法開實現這一目的。 call方法接收命令名稱和數組形式的命令參數：

/** * 執行控制台命令 * * @return mixed */public function handle(){    $this->call('email:send', [        'user' => 1, '--queue' => 'default'    ]);}

如果你想要調用其它控制台命令並阻止其所有輸出，可以使用 callSilent方法。 callSilent方法和 call方法用法一致：

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

