【PHP框架 | Laravel8 系列4】 – Artisan 命令行

【PHP框架 | Laravel8 系列4】 – Artisan 命令行

前言:之前在学习并使用 Laravel 框架过程中,全是碎片化掌握,现在重新学习并记录一次学习的过程。

本文内容对应 Laravel8.* 版本。

直达入口:

  • Laravel 框架专栏
  • Laravel 框架官网

为什么在 系列4 就开始学习 Artisan 了,因为在学习中间件、控制器等内容时,都用到了 Artisan 命令。所以对 Artisan 的学习放到前边喽。

可能第一次接触到 Artisan 的同学不知道他是干啥的,其实一开始我也蒙,谁也别笑话谁😂。

通俗的讲,使用 Artisan 命令,可帮你快速构建好一些基本代码。比如 控制器、中件间等基本代码,这样你就不用像以前一样,创建新文件、在文件中写基本的代码架构。

所以,掌握好 Artisan 命令行的使用,能大大提高你的开发效率与提升你的心情值。

本文学习内容来自 Laravel 官网。


一、提前准备

1.1 操作流程

  1. 打开终端,进入项目目录
  2. 输入 Artisan 命令即可

1.2 打开终端的方法

  • PhpStorm 打开终端: Alt+F12 或者 底部控制栏找到 「终端」,点击进入终端。

  • Windows 用户也可以打开 cmd 进入项目目录。打开 cmd 方法: Win键 + R 后,输入 cmd 即可进入终端。

  • Linux、Mac 用户就不用多说了。


二、Laravel 常用命令

随着学习的开展,更多命令会追加到这里。

2.1 查看所有可用命令

php artisan list

2.2 查看帮助命令

# php artisan help 命令
php artisan help make:controller

三、自定义命令

Artisan 默认提供的命令外,我们还可以自定义命令。

默认存在 app/Console/Commands 目录中,目录默认不存在,会在你第一次成功运行 php artisan make:command 命令时创建。

3.1 生成命令

可用 php artisan make:command 命令名称 生成的新命令,生成后会在 app/Console/Commands 目录创建新的 命令类,命令类中包含默认存在的属性和方法。

# 控制台自定义命令
php artisan make:command SendEmails

‼️ 注意:生成命令后,请先修改类文件中的 signaturedescription 属性以便你在使用 Artisan list 命令时清楚的知道该命令的用法。在 handle 方法中编写执行命令的业务逻辑。

请看以下 Laravel 官网的例子。

<?php
namespace App\Console\Commands;
use App\Models\User;
use App\Support\DripEmailer;
use Illuminate\Console\Command;
class SendEmails extends Command
{
    /**
     * 命令名称及签名
     *
     * @var string
     */
    protected $signature = 'email:send {user}';
    /**
     * 命令描述
     *
     * @var string
     */
    protected $description = 'Send drip e-mails to a user';
    /**
     * 创建命令
     *
     * @return void
     */
    public function __construct()
    {
        parent::__construct();
    }
    /**
     * 执行命令
     *
     * @param  \App\Support\DripEmailer  $drip
     * @return mixed
     */
    public function handle(DripEmailer $drip)
    {
        $drip->send(User::find($this->argument('user')));
    }
}

3.2 闭包命令

闭包命令可替代命令类。在 app/Console/Kernel.php 文件中的 commands 方法中,加载了 routes/console.php 文件。

在该console.php 文件中,可使用 Artisan::command 方法定义闭包路由。方法接受两个参数: 命令的名称和闭包处理的业务逻辑。

请看以下 Laravel 官网的例子。

# 在 routes/console.php 文件中定义
Artisan::command('build {project}', function ($project) {
    $this->info("Building {$project}!");
});

3.3 闭包命令类型约束

除了可接受参数及选项外,闭包命令还可使用类型约束从 服务容器 中解析其他依赖关系。

use App\Models\User;
use App\Support\DripEmailer;
Artisan::command('email:send {user}', function (DripEmailer $drip, $user) {
    $drip->send(User::find($user));
});

3.4 闭包命令描述

在定义闭包命令时,还可能链式调用 describe 方法来为该条命令添加描述。该描述会在执行 php artisan listphp artisan help 命令时显示:

Artisan::command('build {project}', function ($project) {
    $this->info("Building {$project}!");
})->describe('Build the project');

四、自定义输入参数的格式

使用 自定义命令类 时,可在 命令类文件中的 signature 属性中自定义希望用户输入的内容。

名称、参数、选项的约束类似于路由的语法。点我查看 – Laravel8 路由文档

4.1 自定义参数

用户提供的参数和选项都使用 花括号{} 包围。例如:

# app/Console/Commands/某一命令类文件中的 signature 属性
# 定义 必填参数
protected $signature = 'email:send {user}';
# 定义 选填参数
protected $signature = 'email:send {user?}';
# 定义 带默认值的可选参数
protected $signature = 'email:send {user=Chon}';

4.2 自定义选项

  • 格式:自定义选项以 两个短横线 -- 作为前缀。

  • 类型:有 接收值 和 不接收值 两种类型。

不接收值

不接收值的自定义选项就是一个 布尔型的「开关」。

官网例子:

# 定义命令格式
protected $signature = 'email:send {user} {--queue}';
# 控制台调用命令
# 如果命令中包含了 --queue 选项,则 queue 的值为 true,未包含 queue 值为 false
php artisan email:send Chon --queue

接收值

接收值就是在选项后边追加 等号 =

官网例子:

# 定义命令格式
protected $signature = 'email:send {user} {--queue=}';
# 也可以 自定义默认值
protected $signature = 'email:send {user} {--queue=default}';
# 也可以 自定义简写,在选项名前使用 | 将选项名称与简写分隔
protected $signature = 'email:send {user} {--Q|queue}';
# 控制台调用命令
php artisan email:send Chon --Q=default

4.3 输入数组

如果想要接收数组参数或选项,可以 星号 * 字符。

# 定义 数组参数
protected $signature = 'email:send {user*}';
# 控制台调用命令,user 数组将为 ['Chon', 'Leslie']
php artisan email:send Chon Leslie
# 定义 数组选项
protected $signature = 'email:send {user} {--queue=*}';
# 控制台调用命令
php artisan email:send Chon --queue=1 --queue=2

4.4 输入描述

可以使用 冒号 : 将参数和描述分开。

protected $signature = 'email:send
                        {user : The ID of the user}
                        {--queue= : Whether the job should be queued}';

五、参数与选项 I/O

定义好命令并执行后,上边说到 handle 方法是处理业务逻辑的,那传递的参数与选项怎么接收啊,别急,接着往下看。

5.1 解析输入

handle 方法中,使用 argumentoption 方法接收参数值与选项值。

/**
 * 执行命令。
 * 处理业务逻辑,如果参数或选项不存在,则返回 null
 * @return mixed
 */
public function handle()
{
    # 接收 参数
    $userId = $this->argument('user');
    # 接收 数组参数
    $userIdArray = $this->arguments('user');
    # 接收 选项值
    $queue = $this->option('queue');
    # 接收 数组选项值
    $queueArray = $this->options('queue');
    // 处理业务逻辑
}

5.2 交互式输入

/**
 * 执行命令
 *
 * @return mixed
 */
public function handle()
{
    # 询问式输入
    $name = $this->ask('What is your name?');
    # 询问式输入,用户输入时有隐藏效果
    $password = $this->secret('What is the password?');
    # 请求确认,输入 y 或 yes 则为 true,否则为 false
    if ($this->confirm('Do you wish to continue?')) {
    	//
	}
    # 自动补全方式,但用户可忽略自动补全并进行任意输入
    $name = $this->anticipate('What is your name?', ['Taylor', 'Dayle']);
    # 自动补全方式,闭包调用。每当用户输入字符时,闭包调用后并返回一个可供自动补全的选项的数组
    $name = $this->anticipate('What is your name?', function ($input) {
   		// 返回自动补全的选项...
	});
    # 多选问题处理,一共5个参数。
    	# 第一个参数 问题
    	# 第二个参数 给默认提示
    	# 第三个参数 处理用户没有选择时默认选择
    	# 第四个参数 用于确定选择一个有效的响应的可尝试的最大次数
    	# 第五个参数 是否可以选择多个答案
    $name = $this->choice(
    	'What is your name?',
    	['Taylor', 'Dayle'],
    	$defaultIndex,
    	$maxAttempts = null,
    	$allowMultipleSelections = false
	);
}

5.3 编写输出

要发送输出到控制台,请使用 line、info、comment、question、error 方法。每个方法的提示颜色不同。

/**
 * 执行控制台命令
 *
 * @return mixed
 */
public function handle()
{
    $this->line('Display this on the screen'); # 黑字,无背景
    $this->info('Display this on the screen'); # 绿色字
    $this->comment('Display this on the screen'); # 黄色字
    $this->question('Something went wrong!'); # 黑色字,灰绿背景
    $this->error('Something went wrong!'); # 红色背景
    # 表格布局,例如
    $headers = ['Name', 'Email']; # 表头
    $users = [['Name'=>'Chon', 'Email'=>'123'], ['Name'=>'Leslie', 'Email'=>'456']]; # 内容
    $this->table($headers, $users); # 输出
    # 进度条处理,例如
    # 更多用法,参考 https://symfony.com/doc/current/components/console/helpers/progressbar.html
    $users = [1,2,3,4,5];
    $bar = $this->output->createProgressBar(count($users));
    $bar->start();
    foreach ($users as $user) {
        ## 业务逻辑处理
        $bar->advance();
    }
    $bar->finish();
}

六、注册命令

6.1 调用 load 方法自动注册

这是啥意思呢,就是 Laravel 的控制台内核(app/Console/Kernel.php文件)的 commands 方法调用了 load 方法,load 方法会将 app/Console/Commands 目录中的所有命令自动注册。

你就可以自定义一些命令类放到一个文件夹,使用 load 方法来自动注册你自定义的这些命令。

# app/Console/Kernel.php 文件内容
/**
 * 注册应用命令
 *
 * @return void
 */
protected function commands()
{
    $this->load(__DIR__.'/Commands');
    # 比如:你可以自定义一些命令放到 MoreCommands 目录,这样,所有的命令类都会自动注册
    $this->load(__DIR__.'/MoreCommands');
    // ...
}

6.2 在 commands 属性中手动注册

这又是啥意思呢,就是 Laravel 的控制台内核(app/Console/Kernel.php文件)的 $commands 属性中手动注册命令类。当 Artisan 启动时,该属性中定义的所有命令都会被 服务容器 解析并通过 Artisan 注册。

# app/Console/Kernel.php 文件中定义 $commands 属性
# 例如,定义 SendEmails 命令类
protected $commands = [
    Commands\SendEmails::class
];

七、程序调用命令

在 CLI 之外运行 Artisan 命令,比如在 路由或控制器中调用。

7.1 普通调用

使用 Artisan 门面的 call 方法实现,第一个参数为 命令名称,第二个参数为 数组格式的命令参数与选项。返回退出码。

# 例如在路由中调用
Route::get('/foo', function () {
    # 参数调用
    $exitCode = Artisan::call('email:send', [
        'user' => 1, '--queue' => 'default'
    ]);
    # 传递数组值
    Route::get('/foo', function () {
    	$exitCode = Artisan::call('email:send', [
        	'user' => 1, '--id' => [5, 13]
	    ]);
	});
    # 传递布尔值
    $exitCode = Artisan::call('migrate:refresh', [
    	'--force' => true,
	]);
    # 字符调用
    $exitCode = Artisan::call('email:send 1 --queue=default');
    //
});

7.2 队列调用

使用 Artisan 门面的 queue 方法实现命令队列化,此操作能够让 队列工作进程 将其置于后台处理。在使用该方法前,请确保您已经配置了队列并运行了队列监听器:

# 例如在路由中调用
Route::get('/foo', function () {
    Artisan::queue('email:send', [
        'user' => 1, '--queue' => 'default'
    ]);
    # 还可自定义 连接或队列
    Artisan::queue('email:send', ['user' => 1, '--queue' => 'default'])
        		->onConnection('redis')
		        ->onQueue('commands');
    //
});

7.3 命令相互调用

这是啥意思呢,就是在自定义生成的命令类的 handle 方法中,这个方法上边说过,是处理业务逻辑的,在这个方法中,可调用 call 方法来实现调用其他命令的场景。

# 例如 app/Console/Commands/某个自定义命令类中
/**
 * 执行命令
 *
 * @return mixed
 */
public function handle()
{
    $this->call('email:send', [
        'user' => 1, '--queue' => 'default'
    ]);
    # 使用 callSilent 方法,调用另一命令并抑制所有的输出。
    $this->callSilent('email:send', [
    	'user' => 1, '--queue' => 'default'
	]);
    //
}

八、Stub 定制

这是啥意思啊,就是 php artisan make: 命令可以生成很多种类,比如控制器、中件间等。这些类是使用 stub 文件生成的。

如果你想要对默认生成的类文件内容做些改变,那可以在控制台执行 php artisan stub:publish 命令。

执行完毕后,会在项目根目录中生成 stubs 目录,在这个目录中可自定义生成类的内容,修改并保存后,所做的改变都会在执行 php artisan make: 命令生成想要的类时体现出来。

                       

点击阅读全文

上一篇 2023年 5月 25日 am10:15
下一篇 2023年 5月 25日 am10:16