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>