プロンプト¶
- はじめに
- インストール
- 利用可能なプロンプト
- バリデーション前の入力変換
- フォーム
- 情報メッセージ
- テーブル
- スピン
- プログレスバー
- ターミナルのクリア
- ターミナルの考慮事項
- サポートされていない環境とフォールバック
はじめに¶
Laravel Promptsは、プレースホルダーテキストやバリデーションなどのブラウザライクな機能を備えた、美しくユーザーフレンドリーなフォームをコマンドラインアプリケーションに追加するためのPHPパッケージです。
Laravel Promptsは、Artisanコンソールコマンドでユーザー入力を受け付けるのに最適ですが、任意のコマンドラインPHPプロジェクトでも使用できます。
Note
Laravel PromptsはmacOS、Linux、およびWSLを使用するWindowsをサポートしています。詳細については、サポートされていない環境とフォールバックに関するドキュメントを参照してください。
インストール¶
Laravel Promptsは、最新のLaravelリリースに既に含まれています。
Laravel Promptsは、Composerパッケージマネージャを使用して他のPHPプロジェクトにインストールすることもできます：
利用可能なプロンプト¶
テキスト¶
text関数は、指定された質問をユーザーに提示し、入力を受け付けてからそれを返します：
プレースホルダーテキスト、デフォルト値、および情報ヒントを含めることもできます：
$name = text(
label: 'What is your name?',
placeholder: 'E.g. Taylor Otwell',
default: $user?->name,
hint: 'This will be displayed on your profile.'
);
必須値¶
値の入力を必須にする場合は、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を返すことができます。
あるいは、Laravelのバリデータの力を活用することもできます。そのためには、属性の名前と希望するバリデーションルールを含む配列をvalidate引数に渡します：
テキストエリア¶
textarea関数は、指定された質問をユーザーに提示し、複数行のテキストエリアを介して入力を受け付けてからそれを返します：
プレースホルダーテキスト、デフォルト値、および情報ヒントを含めることもできます：
$story = textarea(
label: 'Tell me a story.',
placeholder: 'This is a story about...',
hint: 'This will be displayed on your profile.'
);
必須値¶
値の入力を必須にする場合は、required引数を渡すことができます：
バリデーションメッセージをカスタマイズしたい場合は、文字列を渡すこともできます：
追加のバリデーション¶
最後に、追加のバリデーションロジックを実行したい場合は、validate引数にクロージャを渡すことができます：
$story = textarea(
label: 'Tell me a story.',
validate: fn (string $value) => match (true) {
strlen($value) < 250 => 'The story must be at least 250 characters.',
strlen($value) > 10000 => 'The story must not exceed 10,000 characters.',
default => null
}
);
クロージャは入力された値を受け取り、バリデーションが通過した場合はエラーメッセージを返すか、nullを返すことができます。
あるいは、Laravelのバリデータの力を活用することもできます。そのためには、属性の名前と希望するバリデーションルールを含む配列をvalidate引数に渡します：
パスワード¶
password関数はtext関数に似ていますが、ユーザーの入力はコンソールに入力されるとマスクされます。これは、パスワードなどの機密情報を尋ねる際に便利です：
プレースホルダーテキストと情報ヒントを含めることもできます：
$password = password(
label: 'What is your password?',
placeholder: 'password',
hint: 'Minimum 8 characters.'
);
必須値¶
値の入力を必須にする場合は、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を返すことができます。
あるいは、Laravelのバリデータの力を活用することもできます。そのためには、属性の名前と希望するバリデーションルールを含む配列をvalidate引数に渡します：
確認¶
ユーザーに「はい」または「いいえ」の確認を求める必要がある場合は、confirm関数を使用できます。ユーザーは矢印キーを使用するか、yまたはnを押して応答を選択できます。この関数はtrueまたはfalseを返します。
デフォルト値、「はい」と「いいえ」のラベルのカスタマイズ、および情報ヒントを含めることもできます：
$confirmed = confirm(
label: 'Do you accept the terms?',
default: false,
yes: 'I accept',
no: 'I decline',
hint: 'The terms must be accepted to continue.'
);
「はい」を必須にする¶
必要に応じて、required引数を渡すことでユーザーに「はい」を選択させることができます：
バリデーションメッセージをカスタマイズしたい場合は、文字列を渡すこともできます：
$confirmed = confirm(
label: 'Do you accept the terms?',
required: 'You must accept the terms to continue.'
);
選択¶
ユーザーに事前定義された選択肢から選択させる必要がある場合は、select関数を使用できます：
use function Laravel\Prompts\select;
$role = select(
label: 'What role should the user have?',
options: ['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'
);
最大5つのオプションが表示されると、リストはスクロールを開始します。これをカスタマイズするには、scroll引数を渡します：
$role = select(
label: 'Which category would you like to assign?',
options: Category::pluck('name', 'id'),
scroll: 10
);
追加のバリデーション¶
他のプロンプト関数とは異なり、select関数はrequired引数を受け付けません。これは、何も選択できないためです。ただし、オプションを提示したいが選択を防ぎたい場合は、validate引数にクロージャを渡すことができます：
$role = select(
label: 'ユーザーにどの役割を割り当てますか？',
options: [
'member' => 'メンバー',
'contributor' => 'コントリビューター',
'owner' => 'オーナー',
],
validate: fn (string $value) =>
$value === 'owner' && User::where('role', 'owner')->exists()
? 'オーナーは既に存在します。'
: null
);
options引数が連想配列の場合、クロージャは選択されたキーを受け取ります。そうでない場合は、選択された値を受け取ります。クロージャはエラーメッセージを返すか、バリデーションが通過した場合はnullを返すことができます。
複数選択¶
ユーザーが複数のオプションを選択できるようにする必要がある場合、multiselect関数を使用できます：
use function Laravel\Prompts\multiselect;
$permissions = multiselect(
label: 'どの権限を割り当てますか？',
options: ['読み取り', '作成', '更新', '削除']
);
デフォルトの選択肢と情報ヒントを指定することもできます：
use function Laravel\Prompts\multiselect;
$permissions = multiselect(
label: 'どの権限を割り当てますか？',
options: ['読み取り', '作成', '更新', '削除'],
default: ['読み取り', '作成'],
hint: '権限はいつでも更新できます。'
);
options引数に連想配列を渡して、選択されたオプションのキーを返すようにすることもできます：
$permissions = multiselect(
label: 'どの権限を割り当てますか？',
options: [
'read' => '読み取り',
'create' => '作成',
'update' => '更新',
'delete' => '削除',
],
default: ['read', 'create']
);
リストがスクロールを開始する前に最大5つのオプションが表示されます。これをカスタマイズするには、scroll引数を渡すことができます：
$categories = multiselect(
label: 'どのカテゴリを割り当てますか？',
options: Category::pluck('name', 'id'),
scroll: 10
);
値の必須化¶
デフォルトでは、ユーザーは0個以上のオプションを選択できます。代わりに1つ以上のオプションを強制するには、required引数を渡すことができます：
$categories = multiselect(
label: 'どのカテゴリを割り当てますか？',
options: Category::pluck('name', 'id'),
required: true
);
バリデーションメッセージをカスタマイズしたい場合は、required引数に文字列を渡すことができます：
$categories = multiselect(
label: 'どのカテゴリを割り当てますか？',
options: Category::pluck('name', 'id'),
required: '少なくとも1つのカテゴリを選択する必要があります'
);
追加のバリデーション¶
オプションを提示するが選択を防ぐ必要がある場合、validate引数にクロージャを渡すことができます：
$permissions = multiselect(
label: 'ユーザーにどの権限を割り当てますか？',
options: [
'read' => '読み取り',
'create' => '作成',
'update' => '更新',
'delete' => '削除',
],
validate: fn (array $values) => ! in_array('read', $values)
? 'すべてのユーザーは読み取り権限を必要とします。'
: null
);
options引数が連想配列の場合、クロージャは選択されたキーを受け取ります。そうでない場合は、選択された値を受け取ります。クロージャはエラーメッセージを返すか、バリデーションが通過した場合はnullを返すことができます。
提案¶
suggest関数は、可能な選択肢に対して自動補完を提供するために使用できます。ユーザーは自動補完のヒントに関係なく、任意の回答を提供できます：
また、suggest関数の2番目の引数としてクロージャを渡すこともできます。クロージャは、ユーザーが入力文字を入力するたびに呼び出されます。クロージャは、ユーザーの入力を含む文字列パラメータを受け取り、自動補完のためのオプションの配列を返す必要があります：
$name = suggest(
label: 'あなたの名前は何ですか？',
options: fn ($value) => collect(['Taylor', 'Dayle'])
->filter(fn ($name) => Str::contains($name, $value, ignoreCase: true))
)
プレースホルダーテキスト、デフォルト値、情報ヒントを含めることもできます：
$name = suggest(
label: 'あなたの名前は何ですか？',
options: ['Taylor', 'Dayle'],
placeholder: '例：Taylor',
default: $user?->name,
hint: 'これはあなたのプロフィールに表示されます。'
);
必須の値¶
値の入力を必須にする場合、required引数を渡すことができます：
バリデーションメッセージをカスタマイズしたい場合は、文字列を渡すこともできます：
追加のバリデーション¶
最後に、追加のバリデーションロジックを実行したい場合、validate引数にクロージャを渡すことができます：
$name = suggest(
label: 'あなたの名前は何ですか？',
options: ['Taylor', 'Dayle'],
validate: fn (string $value) => match (true) {
strlen($value) < 3 => '名前は少なくとも3文字である必要があります。',
strlen($value) > 255 => '名前は255文字を超えてはいけません。',
default => null
}
);
クロージャは入力された値を受け取り、エラーメッセージを返すか、バリデーションが通過した場合はnullを返すことができます。
また、Laravelのバリデータの力を活用することもできます。そのためには、属性の名前と希望するバリデーションルールを含む配列をvalidate引数に渡します：
$name = suggest(
label: 'あなたの名前は何ですか？',
options: ['Taylor', 'Dayle'],
validate: ['name' => 'required|min:3|max:255']
);
検索¶
ユーザーが選択するためのオプションが多い場合、search関数を使用すると、ユーザーは検索クエリを入力して結果をフィルタリングし、矢印キーを使用してオプションを選択できます：
use function Laravel\Prompts\search;
$id = search(
label: 'メールを受け取るユーザーを検索',
options: fn (string $value) => strlen($value) > 0
? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
: []
);
クロージャは、ユーザーがこれまでに入力したテキストを受け取り、オプションの配列を返す必要があります。連想配列を返す場合、選択されたオプションのキーが返されます。そうでない場合、その値が返されます。
プレースホルダーテキストと情報ヒントを含めることもできます：
$id = search(
label: 'メールを受け取るユーザーを検索',
placeholder: '例：Taylor Otwell',
options: fn (string $value) => strlen($value) > 0
? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
: [],
hint: 'ユーザーはすぐにメールを受け取ります。'
);
リストがスクロールを開始する前に最大5つのオプションが表示されます。これをカスタマイズするには、scroll引数を渡すことができます：
$id = search(
label: 'メールを受け取るユーザーを検索',
options: fn (string $value) => strlen($value) > 0
? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
: [],
scroll: 10
);
追加のバリデーション¶
追加のバリデーションロジックを実行したい場合、validate引数にクロージャを渡すことができます：
$id = search(
label: 'メールを受け取るユーザーを検索',
options: fn (string $value) => strlen($value) > 0
? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
: [],
validate: function (int|string $value) {
$user = User::findOrFail($value);
if ($user->opted_out) {
return 'このユーザーはメールの受信をオプトアウトしています。';
}
}
);
optionsクロージャが連想配列を返す場合、クロージャは選択されたキーを受け取ります。そうでない場合、選択された値を受け取ります。クロージャはエラーメッセージを返すか、バリデーションが通過した場合はnullを返すことができます。
複数検索¶
検索可能なオプションが多く、ユーザーが複数の項目を選択できるようにする必要がある場合、multisearch関数を使用すると、ユーザーは検索クエリを入力して結果をフィルタリングし、矢印キーとスペースバーを使用してオプションを選択できます：
use function Laravel\Prompts\multisearch;
$ids = multisearch(
'メールを受け取るユーザーを検索',
fn (string $value) => strlen($value) > 0
? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
: []
);
クロージャは、ユーザーがこれまでに入力したテキストを受け取り、オプションの配列を返す必要があります。連想配列を返す場合、選択されたオプションのキーが返されます。そうでない場合、その値が返されます。
プレースホルダーテキストと情報ヒントを含めることもできます：
$ids = multisearch(
label: 'メールを受け取るユーザーを検索',
placeholder: '例：Taylor Otwell',
options: fn (string $value) => strlen($value) > 0
? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
: [],
hint: 'ユーザーはすぐにメールを受け取ります。'
);
リストがスクロールを開始する前に最大5つのオプションが表示されます。これをカスタマイズするには、scroll引数を提供することができます：
$ids = multisearch(
label: 'メールを受け取るユーザーを検索',
options: fn (string $value) => strlen($value) > 0
? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
: [],
scroll: 10
);
値の必須化¶
デフォルトでは、ユーザーはゼロ以上のオプションを選択できます。代わりに1つ以上のオプションを強制するために、required引数を渡すことができます:
$ids = multisearch(
label: 'メールを受け取るユーザーを検索してください',
options: fn (string $value) => strlen($value) > 0
? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
: [],
required: true
);
バリデーションメッセージをカスタマイズしたい場合は、required引数に文字列を渡すこともできます:
$ids = multisearch(
label: 'メールを受け取るユーザーを検索してください',
options: fn (string $value) => strlen($value) > 0
? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
: [],
required: '少なくとも1人のユーザーを選択してください。'
);
追加のバリデーション¶
追加のバリデーションロジックを実行したい場合は、validate引数にクロージャを渡すことができます:
$ids = multisearch(
label: 'メールを受け取るユーザーを検索してください',
options: fn (string $value) => strlen($value) > 0
? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
: [],
validate: function (array $values) {
$optedOut = User::whereLike('name', '%a%')->findMany($values);
if ($optedOut->isNotEmpty()) {
return $optedOut->pluck('name')->join(', ', ', and ').' はオプトアウトしています。';
}
}
);
optionsクロージャが連想配列を返す場合、クロージャは選択されたキーを受け取ります。それ以外の場合は、選択された値を受け取ります。クロージャはエラーメッセージを返すか、バリデーションが通過した場合はnullを返すことができます。
一時停止¶
pause関数は、ユーザーに情報テキストを表示し、Enter / Returnキーを押して続行することを確認するために待機するために使用できます:
バリデーション前の入力変換¶
バリデーションが行われる前にプロンプトの入力を変換したい場合があります。例えば、提供された文字列から空白を削除したい場合です。これを実現するために、多くのプロンプト関数はクロージャを受け取るtransform引数を提供します:
$name = text(
label: 'あなたの名前は何ですか？',
transform: fn (string $value) => trim($value),
validate: fn (string $value) => match (true) {
strlen($value) < 3 => '名前は少なくとも3文字以上である必要があります。',
strlen($value) > 255 => '名前は255文字を超えてはいけません。',
default => null
}
);
フォーム¶
多くの場合、追加のアクションを実行する前に情報を収集するために、複数のプロンプトが順番に表示されます。form関数を使用して、ユーザーが完了するためのグループ化されたプロンプトセットを作成できます:
use function Laravel\Prompts\form;
$responses = form()
->text('あなたの名前は何ですか？', required: true)
->password('あなたのパスワードは何ですか？', validate: ['password' => 'min:8'])
->confirm('利用規約に同意しますか？')
->submit();
submitメソッドは、フォームのプロンプトからのすべての応答を含む数値インデックス付き配列を返します。ただし、各プロンプトにname引数を介して名前を提供することができます。名前が提供されると、名前付きプロンプトの応答はその名前を介してアクセスできます:
use App\Models\User;
use function Laravel\Prompts\form;
$responses = form()
->text('あなたの名前は何ですか？', required: true, name: 'name')
->password(
label: 'あなたのパスワードは何ですか？',
validate: ['password' => 'min:8'],
name: 'password'
)
->confirm('利用規約に同意しますか？')
->submit();
User::create([
'name' => $responses['name'],
'password' => $responses['password'],
]);
form関数を使用する主な利点は、ユーザーがCTRL + Uを使用してフォーム内の前のプロンプトに戻ることができることです。これにより、ユーザーはミスを修正したり、選択を変更したりすることができ、フォーム全体をキャンセルして再開する必要がなくなります。
フォーム内のプロンプトをより細かく制御する必要がある場合は、プロンプト関数を直接呼び出す代わりにaddメソッドを呼び出すことができます。addメソッドは、ユーザーが提供した以前のすべての応答を渡されます:
use function Laravel\Prompts\form;
use function Laravel\Prompts\outro;
$responses = form()
->text('あなたの名前は何ですか？', required: true, name: 'name')
->add(function ($responses) {
return text("{$responses['name']}さんは何歳ですか？");
}, name: 'age')
->submit();
outro("あなたの名前は{$responses['name']}で、{$responses['age']}歳です。");
情報メッセージ¶
note、info、warning、error、alert関数を使用して情報メッセージを表示できます:
テーブル¶
table関数を使用すると、複数の行と列のデータを簡単に表示できます。必要なのは、列名とテーブルのデータを提供することだけです:
use function Laravel\Prompts\table;
table(
headers: ['Name', 'Email'],
rows: User::all(['name', 'email'])->toArray()
);
スピン¶
spin関数は、指定されたコールバックを実行しながらスピナーとオプションのメッセージを表示します。これは、進行中のプロセスを示し、完了時にコールバックの結果を返します:
use function Laravel\Prompts\spin;
$response = spin(
message: '応答を取得中...',
callback: fn () => Http::get('http://example.com')
);
Warning
spin関数は、スピナーをアニメーション化するためにpcntl PHP拡張機能を必要とします。この拡張機能が利用できない場合、スピナーの静的バージョンが表示されます。
プログレスバー¶
長時間実行されるタスクの場合、タスクがどの程度完了しているかをユーザーに知らせるプログレスバーを表示すると便利です。progress関数を使用すると、Laravelはプログレスバーを表示し、指定された反復可能な値を反復するたびに進行させます:
use function Laravel\Prompts\progress;
$users = progress(
label: 'ユーザーを更新中',
steps: User::all(),
callback: fn ($user) => $this->performTask($user)
);
progress関数はマップ関数のように動作し、コールバックの各反復の戻り値を含む配列を返します。
コールバックはLaravel\Prompts\Progressインスタンスも受け取ることができ、各反復でラベルとヒントを変更できます:
$users = progress(
label: 'ユーザーを更新中',
steps: User::all(),
callback: function ($user, $progress) {
$progress
->label("{$user->name}を更新中")
->hint("作成日: {$user->created_at}");
return $this->performTask($user);
},
hint: 'これには時間がかかる場合があります。'
);
プログレスバーの進行をより手動で制御する必要がある場合があります。まず、プロセスが反復するステップの総数を定義します。次に、各アイテムを処理した後にadvanceメソッドを介してプログレスバーを進行させます:
$progress = progress(label: 'ユーザーを更新中', steps: 10);
$users = User::all();
$progress->start();
foreach ($users as $user) {
$this->performTask($user);
$progress->advance();
}
$progress->finish();
ターミナルのクリア¶
clear関数を使用してユーザーのターミナルをクリアできます:
ターミナルの考慮事項¶
ターミナルの幅¶
ラベル、オプション、またはバリデーションメッセージの長さがユーザーのターミナルの「列」数を超える場合、自動的に切り詰められて適合します。ユーザーがより狭いターミナルを使用している可能性がある場合、これらの文字列の長さを最小限に抑えることを検討してください。一般的に安全な最大長は、80文字のターミナルをサポートするための74文字です。
ターミナルの高さ¶
scroll引数を受け取るプロンプトの場合、設定された値は自動的にユーザーのターミナルの高さに合わせて調整され、バリデーションメッセージのスペースも含まれます。
サポートされていない環境とフォールバック¶
Laravel PromptsはmacOS、Linux、およびWSLを使用したWindowsをサポートしています。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) {
$question = new Question($prompt->label, $prompt->default);
$question->setValidator(function ($answer) use ($prompt) {
if ($prompt->required && $answer === null) {
throw new \RuntimeException('This value is required.');
}
if ($prompt->validate) {
$error = ($prompt->validate)($answer);
if ($error) {
throw new \RuntimeException($error);
}
}
return $answer;
});
return (new SymfonyStyle(Input::createFromGlobals(), Output::createFromGlobals()))
->askQuestion($question);
});
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 : '必須項目です。'
);
}
if ($prompt->validate) {
$error = ($prompt->validate)($answer ?? '');
if ($error) {
throw new \RuntimeException($error);
}
}
return $answer;
});
return (new SymfonyStyle($input, $output))
->askQuestion($question);
});
フォールバックは、各プロンプトクラスに対して個別に設定する必要があります。クロージャはプロンプトクラスのインスタンスを受け取り、プロンプトに適した型を返す必要があります。 ```