【Laravel】意外と簡単！自作artisanコマンドにヘルプを付ける
こんにちは。今回は自作のartisanコマンドにヘルプを付ける方法を解説します。ヘルプを付けることでコンソール上からコマンドの使い方を確認できるようになります。作成方法は簡単なので是非習得して、使いやすいコマンドにしていきましょう。
ヘルプとは
コマンドライン上からartisan コマンドの使い方を確認できる機能です。Laravelが提供しているartisanコマンドには基本的に全てヘルプがついています。以下のように使います。
php artisan help [コマンド名]ヘルプがどのように表示されるか確認してみましょう。artisan migrateコマンドのヘルプを見てみます。
php artisan help migrate
Description:
Run the database migrations
Usage:
migrate [options]
Options:
--database[=DATABASE] The database connection to use
--force Force the operation to run when in production
--path[=PATH] The path(s) to the migrations files to be executed (multiple values allowed)
--realpath Indicate any provided migration file paths are pre-resolved absolute paths
--schema-path[=SCHEMA-PATH] The path to a schema dump file
--pretend Dump the SQL queries that would be run
--seed Indicates if the seed task should be re-run
--step Force the migrations to be run so they can be rolled back individually
-h, --help Display help for the given command. When no command is given display help for the list command
-q, --quiet Do not output any message
-V, --version Display this application version
--ansi|--no-ansi Force (or disable --no-ansi) ANSI output
-n, --no-interaction Do not ask any interactive question
--env[=ENV] The environment the command should run under
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
e-seventh@penguin:~/src/sample$
各部分の説明を大まかに書くと以下のような感じです。
| description | コマンドの概要説明 |
| usage | コマンドの呼び出し方。引数やオプションの順番など。 |
| options | 使用できるオプションの種類 |
このように詳細な説明が表示されます。
自作のartisanコマンドのヘルプを作る
コマンド作成
まずはartisanコマンドを作ります。make:commandを利用します。
php artisan make:command MailSendapp/console/Command/MailSend.phpが作成されました。
コマンド名の決定、引数、オプションを追加
今回は引数やオプションのヘルプを作りたいので、作成したMailSend.phpに引数、オプションを追加していきます。
/**
* The name and signature of the console command.
*
* @var string
*/
protected $signature = 'mail:send {user} {--queue}';
$sigmatureにコマンド名と引数をまとめて定義できます。コマンド名はmail:sendとし、user引数と–queueオプションを追加しました。
ヘルプを作成する
準備は整いましたのでヘルプを作成していきましょう。今回ヘルプに組み込む情報は以下の３点です。
- artisan コマンドの概要説明（description）
- 引数の説明
- オプションの説明
まずは概要説明です。概要は$descriptionに記述します。
/**
* The console command description.
*
* @var string
*/
protected $description = 'send mail to user';
次に引数とオプションの説明です。引数とオプションの各定義の中にコロンで区切って説明を書きます。
/**
* The name and signature of the console command.
*
* @var string
*/
protected $signature = 'mail:send {user : the ID of the user}
{--queue : Whether the job should be queued}';
以上でヘルプの作成は完了です。
ヘルプを見る
早速、作成したヘルプを見てみましょう。
php artisan help mail:send
Description:
send mail to user
Usage:
mail:send [options] [--] <user>
Arguments:
user the ID of the user
Options:
--queue Whether the job should be queued
先程作成した記述が表示されていることを確認できました。
まとめ
今回は自作のartisanコマンドのヘルプを作成する方法を解説しました。いかがでしょう。すごく簡単じゃないですか？私はソースにコメントを書く感覚で書けるくらい簡単だと思いました。ヘルプは作成しておくと利用者にとってかなり便利ですので基本は作っておくことをオススメします。