イントロダクション
Laravel Promptsは、美しくユーザーフレンドリーなUIをコマンドラインアプリケーションに追加するためのPHPパッケージで、プレースホルダテキストやバリデーションなどのブラウザにあるような機能を備えています。
Laravel Promptsは、Artisanコンソールコマンドでユーザー入力を受けるために最適ですが、コマンドラインのPHPプロジェクトでも使用できます。
Note: Laravel PromptsはmacOS、Linux、WindowsのWSLをサポートしています。詳しくは、未サポートの環境とフォールバックのドキュメントをご覧ください。
インストール
Laravelの最新リリースには、はじめからLaravel Promptsを用意してあります。
Composerパッケージマネージャを使用して、他のPHPプロジェクトにLaravel Promptsをインストールすることもできます。
composer require laravel/prompts利用可能なプロンプト
テキスト
text関数は、指定した質問でユーザーに入力を促し、回答を受け、それを返します。
use function Laravel\Prompts\text;
$name = text('What is your name?');プレースホルダ・テキストとデフォルト値、ヒントの情報も指定できます。
$name = text(
label: 'What is your name?',
placeholder: 'E.g. Taylor Otwell',
default: $user?->name,
hint: 'This will be displayed on your profile.'
);必須値
入力値が必須の場合は、required引数を渡してください。
$name = text(
label: 'What is your name?',
required: true
);バリデーション・メッセージをカスタマイズしたい場合は、文字列を渡すこともできます。
$name = text(
label: 'What is your name?',
required: 'Your name is required.'
);追加のバリデーション
最後に、追加のバリデーションロジックを実行したい場合は、validate引数にクロージャを渡します。
$name = text(
label: 'What is your name?',
validate: fn (string $value) => match (true) {
strlen($value) < 3 => 'The name must be at least 3 characters.',
strlen($value) > 255 => 'The name must not exceed 255 characters.',
default => null
}
);クロージャは入力された値を受け取り、エラーメッセージを返すか、バリデーションに合格した場合は、nullを返します。
パスワード
password関数はtext関数と似ていますが、コンソールで入力されるユーザー入力をマスクします。これはパスワードのような機密情報を要求するときに便利です：
use function Laravel\Prompts\password;
$password = password('What is your password?');プレースホルダーのテキストと情報のヒントも含められます。
$password = password(
label: 'What is your password?',
placeholder: 'password',
hint: 'Minimum 8 characters.'
);必須値
入力値が必須の場合は、required引数を渡してください。
$password = password(
label: 'What is your password?',
required: true
);バリデーション・メッセージをカスタマイズしたい場合は、文字列を渡すこともできます。
$password = password(
label: 'What is your password?',
required: 'The password is required.'
);追加のバリデーション
最後に、追加のバリデーションロジックを実行したい場合は、validate引数にクロージャを渡します。
$password = password(
label: 'What is your password?',
validate: fn (string $value) => match (true) {
strlen($value) < 8 => 'The password must be at least 8 characters.',
default => null
}
);クロージャは入力された値を受け取り、エラーメッセージを返すか、バリデーションに合格した場合は、nullを返します。
確認
ユーザーに
"yes／no"の確認を求める必要がある場合は、confirm関数を使います。ユーザーは矢印キーを使うか、yまたはnを押して回答を選択します。この関数はtrueまたはfalseを返します。
use function Laravel\Prompts\confirm;
$confirmed = confirm('Do you accept the terms?');また、デフォルト値、「はい」／「いいえ」ラベルをカスタマイズする文言、情報ヒントも含められます。
$confirmed = confirm(
label: 'Do you accept the terms?',
default: false,
yes: 'I accept',
no: 'I decline',
hint: 'The terms must be accepted to continue.'
);必須の"Yes"
必要であれば、required引数を渡し、ユーザーに"Yes"を選択させることもできます。
$confirmed = confirm(
label: 'Do you accept the terms?',
required: true
);バリデーション・メッセージをカスタマイズしたい場合は、文字列を渡すこともできます。
$confirmed = confirm(
label: 'Do you accept the terms?',
required: 'You must accept the terms to continue.'
);選択
ユーザーにあらかじめ定義された選択肢から選ばせる必要がある場合は、select関数を使います。
use function Laravel\Prompts\select;
$role = select(
'What role should the user have?',
['Member', 'Contributor', 'Owner'],
);デフォルト選択肢と情報のヒントも指定できます。
$role = select(
label: 'What role should the user have?',
options: ['Member', 'Contributor', 'Owner'],
default: 'Owner',
hint: 'The role may be changed at any time.'
);options引数に連想配列を渡し、選択値の代わりにキーを返すこともできます。
$role = select(
label: 'What role should the user have?',
options: [
'member' => 'Member',
'contributor' => 'Contributor',
'owner' => 'Owner'
],
default: 'owner'
);５選択肢を超えると、選択肢がリスト表示されます。scroll引数を渡し、カスタマイズ可能です。
$role = select(
label: 'Which category would you like to assign?',
options: Category::pluck('name', 'id'),
scroll: 10
);バリデーション
他のプロンプト関数とは異なり、他に何も選択できなくなるため、select関数はrequired引数を受けません。しかし、選択肢を提示したいが、選択されないようにする必要がある場合は、validate引数にクロージャを渡してください。
$role = select(
label: 'What role should the user have?',
options: [
'member' => 'Member',
'contributor' => 'Contributor',
'owner' => 'Owner'
],
validate: fn (string $value) =>
$value === 'owner' && User::where('role', 'owner')->exists()
? 'An owner already exists.'
: null
);options引数が連想配列の場合、クロージャは選択されたキーを受け取ります。連想配列でない場合は選択された値を受け取ります。クロージャはエラーメッセージを返すか、バリデーションに成功した場合はnullを返してください。
複数選択
ユーザーが複数の選択肢を選択できるようにする必要がある場合は、multiselect関数を使用します。
use function Laravel\Prompts\multiselect;
$permissions = multiselect(
'What permissions should be assigned?',
['Read', 'Create', 'Update', 'Delete']
);デフォルト選択肢と情報のヒントも指定できます。
use function Laravel\Prompts\multiselect;
$permissions = multiselect(
label: 'What permissions should be assigned?',
options: ['Read', 'Create', 'Update', 'Delete'],
default: ['Read', 'Create'],
hint: 'Permissions may be updated at any time.'
);options引数に連想配列を渡し、選択値の代わりにキーを返させることもできます。
$permissions = multiselect(
label: 'What permissions should be assigned?',
options: [
'read' => 'Read',
'create' => 'Create',
'update' => 'Update',
'delete' => 'Delete'
],
default: ['read', 'create']
);５選択肢を超えると、選択肢がリスト表示されます。scroll引数を渡し、カスタマイズ可能です。
$role = multiselect(
label: 'What categories should be assigned?',
options: Category::pluck('name', 'id'),
scroll: 10
);必須値
デフォルトで、ユーザーは０個以上の選択肢を選択できます。required引数を渡せば、代わりに１つ以上の選択肢を強制できます。
$role = multiselect(
label: 'What categories should be assigned?',
options: Category::pluck('name', 'id'),
required: true,
);バリデーション
選択肢を提示するが、その選択肢が選択されないようにする必要がある場合は、validate引数にクロージャを渡してください。
$permissions = select(
label: 'What permissions should the user have?',
options: [
'read' => 'Read',
'create' => 'Create',
'update' => 'Update',
'delete' => 'Delete'
],
validate: fn (array $values) => ! in_array('read', $values)
? 'All users require the read permission.'
: null
);options引数が連想配列の場合、クロージャは選択されたキーを受け取ります。連想配列でない場合は選択された値を受け取ります。クロージャはエラーメッセージを返すか、バリデーションに成功した場合はnullを返してください。
候補
suggest関数を使用すると、可能性のある選択肢を自動補完できます。ユーザーは自動補完のヒントに関係なく、任意の答えを入力することもできます。
use function Laravel\Prompts\suggest;
$name = suggest('What is your name?', ['Taylor', 'Dayle']);あるいは、suggest関数の第２引数にクロージャを渡すこともできます。クロージャはユーザーが入力文字をタイプするたびに呼び出されます。クロージャは文字列パラメータにこれまでのユーザー入力を受け取り、オートコンプリート用の選択肢配列を返す必要があります。
$name = suggest(
'What is your name?',
fn ($value) => collect(['Taylor', 'Dayle'])
->filter(fn ($name) => Str::contains($name, $value, ignoreCase: true))
)プレースホルダ・テキストとデフォルト値、情報のヒントも指定できます。
$name = suggest(
label: 'What is your name?',
options: ['Taylor', 'Dayle'],
placeholder: 'E.g. Taylor',
default: $user?->name,
hint: 'This will be displayed on your profile.'
);必須値
入力値が必須の場合は、required引数を渡してください。
$name = suggest(
label: 'What is your name?',
options: ['Taylor', 'Dayle'],
required: true
);バリデーション・メッセージをカスタマイズしたい場合は、文字列を渡すこともできます。
$name = suggest(
label: 'What is your name?',
options: ['Taylor', 'Dayle'],
required: 'Your name is required.'
);追加のバリデーション
最後に、追加のバリデーションロジックを実行したい場合は、validate引数にクロージャを渡します。
$name = suggest(
label: 'What is your name?',
options: ['Taylor', 'Dayle'],
validate: fn (string $value) => match (true) {
strlen($value) < 3 => 'The name must be at least 3 characters.',
strlen($value) > 255 => 'The name must not exceed 255 characters.',
default => null
}
);クロージャは入力された値を受け取り、エラーメッセージを返すか、バリデーションに合格した場合は、nullを返します。
検索
ユーザーが選択できる選択肢がたくさんある場合、search機能を使えば、矢印キーを使って選択肢を選択する前に、検索クエリを入力して結果を絞り込むことができます。
use function Laravel\Prompts\search;
$id = search(
'Search for the user that should receive the mail',
fn (string $value) => strlen($value) > 0
? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
: []
);クロージャは、ユーザーがこれまでに入力したテキストを受け取り、 選択肢の配列を返さなければなりません。連想配列を返す場合は選択された選択肢のキーが返され、 そうでない場合はその値が代わりに返されます。
プレースホルダーのテキストと情報のヒントも含められます。
$id = search(
label: 'Search for the user that should receive the mail',
placeholder: 'E.g. Taylor Otwell',
options: fn (string $value) => strlen($value) > 0
? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
: [],
hint: 'The user will receive an email immediately.'
);５選択肢を超えると、選択肢がリスト表示されます。scroll引数を渡し、カスタマイズ可能です。
$id = search(
label: 'Search for the user that should receive the mail',
options: fn (string $value) => strlen($value) > 0
? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
: [],
scroll: 10
);バリデーション
追加のバリデーションロジックを実行したい場合は、validate引数にクロージャを渡します。
$id = search(
label: 'Search for the user that should receive the mail',
options: fn (string $value) => strlen($value) > 0
? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
: []
validate: function (int|string $value) {
$user = User::findOrFail($value);
if ($user->opted_out) {
return 'This user has opted-out of receiving mail.';
}
}
);options引数が連想配列の場合、クロージャは選択されたキーを受け取ります。連想配列でない場合は選択された値を受け取ります。クロージャはエラーメッセージを返すか、バリデーションに成功した場合はnullを返してください。
情報メッセージ
note、info、warning、error、alert関数は、情報メッセージを表示するために使用します。
use function Laravel\Prompts\info;
info('Package installed successfully.');テーブル
table関数を使うと、複数の行や列のデータを簡単に表示できます。指定する必要があるのは、カラム名とテーブルのデータだけです。
use function Laravel\Prompts\table;
table(
['Name', 'Email'],
User::all(['name', 'email'])
);スピン
spin関数は、指定したコールバックを実行している間、オプションのメッセージとともにスピナーを表示します。これは進行中の処理を示す役割を果たし、完了するとコールバックの結果を返します。
use function Laravel\Prompts\spin;
$response = spin(
fn () => Http::get('http://example.com'),
'Fetching response...'
);Warning!!
spin関数でスピナーをアニメーションするために、pcntlPHP拡張モジュールが必要です。この拡張モジュールが利用できない場合は、代わりに静的なスピナーが表示されます。
ターミナルの考察
ターミナルの横幅
ラベルやオプション、バリデーションメッセージの長さが、ユーザーの端末の「列」の文字数を超える場合、自動的に切り捨てます。ユーザーが狭い端末を使う可能性がある場合は、これらの文字列の長さを最小限にする検討をしてください。一般的に安全な最大長は、８０文字の端末をサポートする場合、７４文字です。
ターミナルの高さ
scroll引数を受け入れるプロンプトの場合、設定済み値は、検証メッセージ用のスペースを含めて、ユーザーの端末の高さに合わせて自動的に縮小されます。
未サポートの環境とフォールバック
Laravel PromptsはmacOS、Linux、WindowsのWSLをサポートしています。Windows版のPHPの制限により、現在のところWSL以外のWindowsでは、Laravel Promptsを使用できません。
このため、Laravel PromptsはSymfony Console Question Helperのような代替実装へのフォールバックをサポートしています。
Note: LaravelフレームワークでLaravel Promptsを使用する場合、各プロンプトのフォールバックが設定済みで、未サポートの環境では自動的に有効になります。
フォールバックの条件
Laravelを使用していない場合や、フォールバック動作をカスタマイズする必要がある場合は、PromptクラスのfallbackWhenへブール値を渡してください。
use Laravel\Prompts\Prompt;
Prompt::fallbackWhen(
! $input->isInteractive() || windows_os() || app()->runningUnitTests()
);フォールバックの振る舞い
Laravelを使用していない場合や、フォールバックの動作をカスタマイズする必要がある場合は、各プロンプトクラスのfallbackUsing静的メソッドへクロージャを渡してください。
use Laravel\Prompts\TextPrompt;
use Symfony\Component\Console\Question\Question;
use Symfony\Component\Console\Style\SymfonyStyle;
TextPrompt::fallbackUsing(function (TextPrompt $prompt) use ($input, $output) {
$question = (new Question($prompt->label, $prompt->default ?: null))
->setValidator(function ($answer) use ($prompt) {
if ($prompt->required && $answer === null) {
throw new \RuntimeException(is_string($prompt->required) ? $prompt->required : 'Required.');
}
if ($prompt->validate) {
$error = ($prompt->validate)($answer ?? '');
if ($error) {
throw new \RuntimeException($error);
}
}
return $answer;
});
return (new SymfonyStyle($input, $output))
->askQuestion($question);
});フォールバックは、プロンプトクラスごとに個別に設定する必要があります。クロージャはプロンプトクラスのインスタンスを受け取り、 プロンプトの適切な型を返す必要があります。