Artisan 命令行 · laravel 5.4

<article><h1>Laravel 的 Artisan 命令行工具</h1><ul><li><a href="#introduction">介紹</a></li><li><a href="#writing-commands">編寫命令</a><ul><li><a href="#generating-commands">生成命令</a></li><li><a href="#command-structure">命令結構</a></li><li><a href="#closure-commands">閉包命令</a></li></ul></li><li><a href="#defining-input-expectations">定義預期的輸入</a><ul><li><a href="#arguments">參數</a></li><li><a href="#options">選項</a></li><li><a href="#input-arrays">輸入數組</a></li><li><a href="#input-descriptions">輸入說明</a></li></ul></li><li><a href="#command-io">I/O 命令</a><ul><li><a href="#retrieving-input">獲取輸入</a></li><li><a href="#prompting-for-input">輸入提示</a></li><li><a href="#writing-output">編寫輸出</a></li></ul></li><li><a href="#registering-commands">注冊命令</a></li><li><a href="#programmatically-executing-commands">程序內部調用命令</a><ul><li><a href="#calling-commands-from-other-commands">命令中調用其它命令</a></li></ul></li></ul><a name="introduction"></a><h2><a href="#introduction">介紹</a></h2><code class=" language-php">Artisan</code> 是 Laravel 的命令行接口的名稱，它提供了許多實用的命令來幫助你開發 Laravel 應用，要查看所有的 <code class=" language-php">Artisan</code> 命令列表，可以使用 <code class=" language-php">list</code> 命令：<pre class=" language-php"><code class=" language-php">php artisan list</code></pre>每個命令也包含了「幫助」界面，它會顯示并概述命令可使的參數及選項。只需要在命令前面加上 <code class=" language-php">help</code> 即可顯示命令幫助界面：<pre class=" language-php"><code class=" language-php">php artisan help migrate</code></pre><h4>Laravel REPL</h4>所有的 Laravel 應用都包括 Tinker，一個基于 <a href="https://github.com/bobthecow/psysh">PsySH</a> 開發的 REPL 包。Tinker 讓你可以在命令行中與你整個的 Laravel 應用進行交互，包括 Eloquent ORM，任務，事件等等。運行 <code class=" language-php">tinker</code> 命令進入 Tinker 環境：<pre class=" language-php"><code class=" language-php">php artisan tinker</code></pre><a name="writing-commands"></a><h2><a href="#writing-commands">編寫命令</a></h2>除了 <code class=" language-php">Artisan</code> 提供的命令之外，還可以創建自定義命令。自定義命令默認存儲在 <code class=" language-php">app/Console/Commands</code> 目錄，當然，你也可以修改 <code class=" language-php">composer.json</code> 配置來指定你想要存放的目錄。<a name="generating-commands"></a><h3>生成命令</h3>要創建一個新的命令，可以使用 <code class=" language-php">make:command</code> 命令。這個命令會創建一個命令類并存放在 <code class=" language-php">app/Console/Commands</code> 目錄。不必擔心不存在這個目錄，運行 <code class=" language-php">make:command</code> 命令時會首先創建這個目錄。生成的命令將會包括所有默認存在的屬性和方法：<pre class=" language-php"><code class=" language-php">php artisan make:command SendEmails</code></pre>接下來，你需要在 Artisan CLI 里執行之前<a href="#registering-commands">注冊命令</a>。<a name="command-structure"></a><h3>命令結構</h3>命令生成以后，應先填寫類的 <code class=" language-php">signature</code> 和 <code class=" language-php">description</code> 屬性，之后可以在使用 <code class=" language-php">list</code> 命令是顯示出來。執行命令是調用 <code class=" language-php">handle</code> 方法，可以把你的命令邏輯放到這個方法中。<blockquote class="has-icon tip"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="56.6px" height="87.5px" viewBox="0 0 56.6 87.5" enable-background="new 0 0 56.6 87.5" xml:space="preserve"><path fill="#FFFFFF" d="M28.7 64.5c-1.4 0-2.5-1.1-2.5-2.5v-5.7 -5V41c0-1.4 1.1-2.5 2.5-2.5s2.5 1.1 2.5 2.5v10.1 5 5.8C31.2 63.4 30.1 64.5 28.7 64.5zM26.4 0.1C11.9 1 0.3 13.1 0 27.7c-0.1 7.9 3 15.2 8.2 20.4 0.5 0.5 0.8 1 1 1.7l3.1 13.1c0.3 1.1 1.3 1.9 2.4 1.9 0.3 0 0.7-0.1 1.1-0.2 1.1-0.5 1.6-1.8 1.4-3l-2-8.4 -0.4-1.8c-0.7-2.9-2-5.7-4-8 -1-1.2-2-2.5-2.7-3.9C5.8 35.3 4.7 30.3 5.4 25 6.7 14.5 15.2 6.3 25.6 5.1c13.9-1.5 25.8 9.4 25.8 23 0 4.1-1.1 7.9-2.9 11.2 -0.8 1.4-1.7 2.7-2.7 3.9 -2 2.3-3.3 5-4 8L41.4 53l-2 8.4c-0.3 1.2 0.3 2.5 1.4 3 0.3 0.2 0.7 0.2 1.1 0.2 1.1 0 2.2-0.8 2.4-1.9l3.1-13.1c0.2-0.6 0.5-1.2 1-1.7 5-5.1 8.2-12.1 8.2-19.8C56.4 12 42.8-1 26.4 0.1zM43.7 69.6c0 0.5-0.1 0.9-0.3 1.3 -0.4 0.8-0.7 1.6-0.9 2.5 -0.7 3-2 8.6-2 8.6 -1.3 3.2-4.4 5.5-7.9 5.5h-4.1H28h-0.5 -3.6c-3.5 0-6.7-2.4-7.9-5.7l-0.1-0.4 -1.8-7.8c-0.4-1.1-0.8-2.1-1.2-3.1 -0.1-0.3-0.2-0.5-0.2-0.9 0.1-1.3 1.3-2.1 2.6-2.1H41C42.4 67.5 43.6 68.2 43.7 69.6zM37.7 72.5H26.9c-4.2 0-7.2 3.9-6.3 7.9 0.6 1.3 1.8 2.1 3.2 2.1h4.1 0.5 0.5 3.6c1.4 0 2.7-0.8 3.2-2.1L37.7 72.5z"></path></svg></div> 大部分的代碼復用，保持你的代碼輕量并讓它們延遲到應用服務中完成任務是個不錯的實踐。在下面這個例子中，我們注入了一個服務類去執行發送郵件的繁重任務。</blockquote>讓我們看這個簡單的命令例子，<code class=" language-php">Command</code> 類構造器允許注入需要的依賴，Laravel 的<a href="/docs/5.4/container">服務容器</a> 將會自動注入構造函數中所有帶類型約束的依賴：<pre class=" language-php"><code class=" language-php"><?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'; /** * 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'))); } }</code></pre><a name="closure-commands"></a><h3>閉包命令</h3>閉包命令提供一個替代定義命令方法的類。同樣的路由閉包是控制器的一種替代方法，這種命令閉包可以替換命令類。使用 <code class=" language-php">app/Console/Kernel.php</code> 文件的 <code class=" language-php">commands</code> 方法，需要 Laravel 在 <code class=" language-php">routes/console.php</code> 注冊：<pre class=" language-php"><code class=" language-php">/** * Register the Closure based commands for the application. * * @return void */ protected function commands() { require base_path('routes/console.php'); }</code></pre>雖然這個文件沒有定義 HTTP 路由，它定義了基于控制臺的入口點（路由）到你的應用中，在這個文件中，你可以使用 <code class=" language-php">Artisan::command</code> 方法定義所有基于路由的閉包，<code class=" language-php">command</code> 方法接收兩個參數：<a href="#defining-input-expectations">命令簽名</a>和一個接收命令參數和選項的閉包：<pre class=" language-php"><code class=" language-php">Artisan::command('build {project}', function ($project) { $this->info("Building {$project}!"); });</code></pre>閉包綁定下面的命令實例，因此你可以訪問所有的輔助方法，您也可以訪問一個完整的命令類。<h4>類型提示依賴</h4>除了接收命令的參數和選項外，命令閉包也可以使用類型提示來指定 <a href="/docs/5.4/container">服務容器</a> 之外的額外依賴：<pre class=" language-php"><code class=" language-php">use App\User; use App\DripEmailer; Artisan::command('email:send {user}', function (DripEmailer $drip, $user) { $drip->send(User::find($user)); });</code></pre><h4>閉包命令描述</h4>當定義一個基于命令的閉包時，你可以使用 <code class=" language-php">describe</code> 方法來為命令添加描述。這個描述將會在你執行 <code class=" language-php">php artisan list</code> 或 <code class=" language-php">php artisan help</code> 命令時顯示：<pre class=" language-php"><code class=" language-php">Artisan::command('build {project}', function ($project) { $this->info("Building {$project}!"); })->describe('Build the project');</code></pre><a name="defining-input-expectations"></a><h2><a href="#defining-input-expectations">定義預期的輸入</a></h2>在你編寫控制臺命令時，通常通過參數和選項收集用戶輸入，Laravel 使這項操作變得很方便，你可以在命令里使用 <code class=" language-php">signature</code> 屬性。 <code class=" language-php">signature</code> 屬性通過一個類似路由風格的語法讓用戶為命令定義名稱，參數和選項。<a name="arguments"></a><h3>參數</h3>所有用戶提供的參數及選項都包在大括號中。如以下例子，此命令會定義一個 必須 的參數： <code class=" language-php">user</code> ：<pre class=" language-php"><code class=" language-php">/** * The name and signature of the console command. * * @var string */ protected $signature = 'email:send {user}';</code></pre>您也可以創建可選參數，并定義參數的默認值：<pre class=" language-php"><code class=" language-php">// Optional argument... email:send {user?} // Optional argument with default value... email:send {user=foo}</code></pre><a name="options"></a><h3>選項</h3>選項，和參數一樣，也是用戶輸入的一種格式，不過當使用選項時，需要在命令前加兩個連字符號 (<code class=" language-php">--</code>) 的前綴，有兩種類型的選項：接收一個值和不接受值。選項不接收一個值作為布爾值的 <code class=" language-php">switch</code> 。讓我們看一個選項的例子：<pre class=" language-php"><code class=" language-php">/** * The name and signature of the console command. * * @var string */ protected $signature = 'email:send {user} {--queue}';</code></pre>在這個例子中,當調用 <code class=" language-php">Artisan</code> 命令時，<code class=" language-php">--queue</code> 這個選項可以被明確的指定。如果 <code class=" language-php">--queue</code> 被當成輸入時，這個選項的的值為 <code class=" language-php">true</code> ，否則這個值為 <code class=" language-php">false</code> ：<pre class=" language-php"><code class=" language-php">php artisan email:send 1 --queue</code></pre><a name="options-with-values"></a><h4>有值的選項</h4>接下來，我們看下有值的選項。如果用戶必須為選項指定一個值，會在選項的后面加一個 <code class=" language-php">=</code> 的后綴：<pre class=" language-php"><code class=" language-php">/** * The name and signature of the console command. * * @var string */ protected $signature = 'email:send {user} {--queue=}';</code></pre>在這個例子中，用戶可以想下面這個例子傳遞一個值：<pre class=" language-php"><code class=" language-php">php artisan email:send 1 --queue=default</code></pre>您可以通過指定選項名稱后的默認值將默認值分配給選項。如果用戶沒有輸入一個值，將會采用默認的值：<pre class=" language-php"><code class=" language-php">email:send {user} {--queue=default}</code></pre><a name="option-shortcuts"></a><h4>選項快捷鍵</h4>當定義一個定義選項時，可以分配一個快捷鍵。你可以在選項前使用一個 <code class=" language-php">|</code> 分隔符將簡寫和完整選項名分開：<pre class=" language-php"><code class=" language-php">email:send {user} {--Q|queue}</code></pre><a name="input-arrays"></a><h3>數組輸入</h3>如果你想使用數組輸入方式定義參數或選項，你可以使用 <code class=" language-php">*</code> 符號。首先，我們先看一個數組輸入的實例：<pre class=" language-php"><code class=" language-php">email:send {user*}</code></pre>調用此方法時，<code class=" language-php">user</code> 參數通過命令行輸入。例如，下面這個命令將會為 <code class=" language-php">user</code> 設置 <code class=" language-php">['foo', 'bar']</code> ：<pre class=" language-php"><code class=" language-php">php artisan email:send foo bar</code></pre>在定義一個使用數組輸入時，每個輸入選項值的命令都要在選項名稱前加前綴：<pre class=" language-php"><code class=" language-php">email:send {user} {--id=*} php artisan email:send --id=1 --id=2</code></pre><a name="input-descriptions"></a><h3>輸入描述</h3>您可以通過在使用一個冒號分離參數來分配輸入參數和選項的說明。如果你需要一個小的額外的空間來定義你的命令，可以多行定義你的擴展：<pre class=" language-php"><code class=" language-php">/** * The name and signature of the console command. * * @var string */ protected $signature = 'email:send {user : The ID of the user} {--queue= : Whether the job should be queued}';</code></pre><a name="command-io"></a><h2><a href="#command-io">I/O 命令</a></h2><a name="retrieving-input"></a><h3>獲取輸入</h3>在命令執行的時，你可以像下面這樣使用 <code class=" language-php">argument</code> 和 <code class=" language-php">option</code> 方法獲取參數和選項：<pre class=" language-php"><code class=" language-php">/** * Execute the console command. * * @return mixed */ public function handle() { $userId = $this->argument('user'); // }</code></pre>如果您需要獲取所有參數作為一個 <code class=" language-php">array</code>，調用 <code class=" language-php">arguments</code> 方法：<pre class=" language-php"><code class=" language-php">$arguments = $this->arguments();</code></pre>選項可以像參數一樣使用 <code class=" language-php">option</code> 方法檢索，獲取所有的選項作為一個 <code class=" language-php">array</code> ，調用 <code class=" language-php">options</code> 方法：<pre class=" language-php"><code class=" language-php">// Retrieve a specific option... $queueName = $this->option('queue'); // Retrieve all options... $options = $this->options();</code></pre>如果參數或選項不存在，將會返回 <code class=" language-php">null</code> 。<a name="prompting-for-input"></a><h3>交互式輸入</h3>除了顯示輸出，您還可以要求用戶在您的命令執行過程中提供輸入。<code class=" language-php">ask</code> 方法將會使用給定問題提示用戶，接收輸入，然后返回用戶輸入到命令：<pre class=" language-php"><code class=" language-php">/** * Execute the console command. * * @return mixed */ public function handle() { $name = $this->ask('What is your name?'); }</code></pre><code class=" language-php">secret</code> 方法和 <code class=" language-php">ask</code> 方法類似，但是用戶輸入在終端中是不可以見的，這個方法在需要用戶輸入像密碼這樣的敏感信息是很有用的：<pre class=" language-php"><code class=" language-php">$password = $this->secret('What is the password?');</code></pre><h4>請求確認</h4>如果你要用戶提供的確認信息，你可以使用 <code class=" language-php">confirm</code> 方法，默認情況下，該方法返回 <code class=" language-php">false</code>，當然，如果你輸入 <code class=" language-php">y</code> 這個方法將會返回 <code class=" language-php">true</code>。<pre class=" language-php"><code class=" language-php">if ($this->confirm('Do you wish to continue?')) { // }</code></pre><h4>自動完成</h4><code class=" language-php">anticipate</code> 方法可用于為可能的選項提供自動完成功能，用戶仍然可以選擇，忽略這個提示：<pre class=" language-php"><code class=" language-php">$name = $this->anticipate('What is your name?', ['Taylor', 'Dayle']);</code></pre><h4>多重選擇</h4>如果你要給用戶一組預設選擇，可以使用 <code class=" language-php">choice</code> 方法，你可以設置默認選項當用戶沒有選擇時：<pre class=" language-php"><code class=" language-php">$name = $this->choice('What is your name?', ['Taylor', 'Dayle'], $default);</code></pre><a name="writing-output"></a><h3>編寫輸出</h3>使用 <code class=" language-php">line</code> 、<code class=" language-php">info</code> 、 <code class=" language-php">comment</code> 、 <code class=" language-php">question</code> 和 <code class=" language-php">error</code> 方法來發送輸出到終端。每個方法都有適當的 ANSI 顏色來作為他們的標識。例如，要顯示一條信息消息給用戶，使用 <code class=" language-php">info</code> 方法。通常，在終端顯示為綠色：<pre class=" language-php"><code class=" language-php">/** * Execute the console command. * * @return mixed */ public function handle() { $this->info('Display this on the screen'); }</code></pre>顯示錯誤信息，使用 <code class=" language-php">error</code> 方法。錯誤信息顯示紅色：<pre class=" language-php"><code class=" language-php">$this->error('Something went wrong!');</code></pre>使用 <code class=" language-php">line</code> 方法可以像平常一樣，沒有顏色輸出。<pre class=" language-php"><code class=" language-php">$this->line('Display this on the screen');</code></pre><h4>數據表布局</h4>table 方法使輸出多行/列格式的數據變得簡單，只需要將頭和行傳遞給該方法，寬度和高度將基于給定數據自動計算：<pre class=" language-php"><code class=" language-php">$headers = ['Name', 'Email']; $users = App\User::all(['name', 'email'])->toArray(); $this->table($headers, $users);</code></pre><h4>進度條</h4>對需要較長時間運行的任務，顯示進度指示器很有用，使用該輸出對象，我們可以開始、前進以及停止該進度條。在開始進度時你必須定義步數，然后每走一步進度條前進一格：<pre class=" language-php"><code class=" language-php">$users = App\User::all(); $bar = $this->output->createProgressBar(count($users)); foreach ($users as $user) { $this->performTask($user); $bar->advance(); } $bar->finish();</code></pre>更多信息請查閱<a href="https://symfony.com/doc/2.7/components/console/helpers/progressbar.html">Symfony Progress Bar 組件的文檔</a>.<a name="registering-commands"></a><h2><a href="#registering-commands">注冊命令</a></h2>命令編寫完成后，需要注冊 Artisan 后才能使用。注冊文件為 <code class=" language-php">app/Console/Kernel.php</code> 。在這個文件中, 你會在 <code class=" language-php">commands</code> 屬性中看到一個命令列表。要注冊你的命令，只需將其加到該列表中即可。當 Artisan 啟動時，所有羅列在這個屬性的命令，都會被 <a href="/docs/5.4/container">服務容器</a> 解析并向 Artisan 注冊：<pre class=" language-php"><code class=" language-php">protected $commands = [ Commands\SendEmails::class ];</code></pre><a name="programmatically-executing-commands"></a><h2><a href="#programmatically-executing-commands">程序內部調用命令</a></h2>有時候你可能希望在 CLI 之外執行 Artisan 命令，例如，你可能希望在路由或控制器中觸發 Artisan 命令，你可以使用 <code class=" language-php">Artisan</code> facade 上的 <code class=" language-php">call</code> 方法來完成。<code class=" language-php">call</code> 方法接收被執行的命令名稱作為第一個參數，命令參數數組作為第二個參數，退出代碼被返回：<pre class=" language-php"><code class=" language-php">Route::get('/foo', function () { $exitCode = Artisan::call('email:send', [ 'user' => 1, '--queue' => 'default' ]); // });</code></pre>在 <code class=" language-php">Artisan</code> facade 使用 <code class=" language-php">queue</code> 方法，可以將 Artisan 命令給后臺的 <a href="/docs/5.4/queues">隊列服務器</a> 運行,在這之前，確保您已配置了您的隊列，并正在運行隊列：<pre class=" language-php"><code class=" language-php">Route::get('/foo', function () { Artisan::queue('email:send', [ 'user' => 1, '--queue' => 'default' ]); // });</code></pre>如果需要指定非接收字符串選項的值，如 <code class=" language-php">migrate:refresh</code> 命令的 <code class=" language-php">--force</code> 值，你可以傳遞一個 <code class=" language-php">true</code> 或者 <code class=" language-php">false</code>：<pre class=" language-php"><code class=" language-php">$exitCode = Artisan::call('migrate:refresh', [ '--force' => true, ]);</code></pre><a name="calling-commands-from-other-commands"></a><h3>命令中調用其它命令</h3>有時候你希望從一個已存在的 Artisan 命令中調用其它命令。你可以使用 <code class=" language-php">call</code> 方法， <code class=" language-php">call</code> 方法接受命令名稱和命令參數的數組：<pre class=" language-php"><code class=" language-php">/** * Execute the console command. * * @return mixed */ public function handle() { $this->call('email:send', [ 'user' => 1, '--queue' => 'default' ]); // }</code></pre>如果你想要調用其它控制臺命令并阻止其所有輸出，可以使用 <code class=" language-php">callSilent</code> 命令。<code class=" language-php">callSilent</code> 和 <code class=" language-php">call</code> 方法用法一樣：<pre class=" language-php"><code class=" language-php">$this->callSilent('email:send', [ 'user' => 1, '--queue' => 'default' ]);</code></pre></article>