Laravel框架 - Artisan 命令篇

目录

一、提前准备

1.1 操作流程

1.2 打开终端的方法

二、Laravel 常用命令 

2.1 查看所有可用命令

2.2 查看帮助命令

三、自定义命令

3.1 生成命令

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

4.1 自定义参数

4.2 自定义选项

不接收值

接收值

4.3 输入数组

4.4 输入描述 

五、参数与选项 I/O

5.1 解析输入

 5.2 交互式输入

5.3 编写输出

六、注册命令

6.1 调用 load 方法自动注册

6.2 在 commands 属性中手动注册

七、程序调用命令

7.1 普通调用

7.2 队列调用

7.3 命令相互调用

---

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

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

 

直达入口：

• Laravel 框架专栏
• Laravel 框架官网
• Laravel 定义调度

一、提前准备

1.1 操作流程

        打开终端，进入项目目录
        输入 Artisan 命令即可

1.2 打开终端的方法

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

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

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

二、Laravel 常用命令 

2.1 查看所有可用命令

php artisan -v

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

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

    请看以下 Laravel 官网的例子。   

 send(User::find($this->argument('user')));
        }
    }

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

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

名称、参数、选项的约束类似于路由的语法。

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 方法中，使用 argument 和 option 方法接收参数值与选项值。

/**
 * 执行命令。
 * 处理业务逻辑，如果参数或选项不存在，则返回 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'
	]);

    //
}