Prompts

イントロダクション
インストール
利用可能なプロンプト
バリデーション前の入力変換
フォーム
情報メッセージ
テーブル
スピン
プログレスバー
ターミナルのクリア
ターミナルに関する考慮事項
非対応環境とフォールバック

イントロダクション

Laravel Promptsは、プレースホルダーテキストやバリデーションといったブラウザのような機能を備え、美しくユーザーフレンドリーなフォームをコマンドラインアプリケーションに追加するためのPHPパッケージです。

Laravel Promptsは、Artisanコンソールコマンドでユーザーからの入力を受け付けるのに最適ですが、どのコマンドラインPHPプロジェクトでも使用できます。

Laravel Promptsは、macOS、Linux、およびWSLを使用するWindowsをサポートしています。詳細については、非対応環境とフォールバックに関するドキュメントを参照してください。

インストール

Laravel Promptsは、Laravelの最新リリースにすでに含まれています。

Laravel Promptsは、Composerパッケージマネージャを使用して他のPHPプロジェクトにインストールすることもできます。

1composer require laravel/prompts

composer require laravel/prompts

利用可能なプロンプト

テキスト

text関数は、指定した質問でユーザーにプロンプトを表示し、入力を受け付け、それを返します。

1use function Laravel\Prompts\text;
2 
3$name = text('What is your name?');

use function Laravel\Prompts\text;

$name = text('What is your name?');

プレースホルダーテキスト、デフォルト値、情報ヒントを含めることもできます。

1$name = text(
2    label: 'What is your name?',
3    placeholder: 'E.g. Taylor Otwell',
4    default: $user?->name,
5    hint: 'This will be displayed on your profile.'
6);

$name = text(
    label: 'What is your name?',
    placeholder: 'E.g. Taylor Otwell',
    default: $user?->name,
    hint: 'This will be displayed on your profile.'
);

必須値

値の入力を必須にしたい場合は、required引数を渡してください。

1$name = text(
2    label: 'What is your name?',
3    required: true
4);

$name = text(
    label: 'What is your name?',
    required: true
);

バリデーションメッセージをカスタマイズしたい場合は、文字列を渡すこともできます。

1$name = text(
2    label: 'What is your name?',
3    required: 'Your name is required.'
4);

$name = text(
    label: 'What is your name?',
    required: 'Your name is required.'
);

追加のバリデーション

最後に、追加のバリデーションロジックを実行したい場合は、validate引数にクロージャを渡します。

1$name = text(
2    label: 'What is your name?',
3    validate: fn (string $value) => match (true) {
4        strlen($value) < 3 => 'The name must be at least 3 characters.',
5        strlen($value) > 255 => 'The name must not exceed 255 characters.',
6        default => null
7    }
8);

$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引数に指定してください。

1$name = text(
2    label: 'What is your name?',
3    validate: ['name' => 'required|max:255|unique:users']
4);

$name = text(
    label: 'What is your name?',
    validate: ['name' => 'required|max:255|unique:users']
);

テキストエリア

textarea関数は、指定された質問をユーザーにプロンプト表示し、複数行のテキストエリアで入力を受け付け、それを返します。

1use function Laravel\Prompts\textarea;
2 
3$story = textarea('Tell me a story.');

use function Laravel\Prompts\textarea;

$story = textarea('Tell me a story.');

プレースホルダーテキスト、デフォルト値、情報ヒントを含めることもできます。

1$story = textarea(
2    label: 'Tell me a story.',
3    placeholder: 'This is a story about...',
4    hint: 'This will be displayed on your profile.'
5);

$story = textarea(
    label: 'Tell me a story.',
    placeholder: 'This is a story about...',
    hint: 'This will be displayed on your profile.'
);

必須値

値の入力を必須にしたい場合は、required引数を渡してください。

1$story = textarea(
2    label: 'Tell me a story.',
3    required: true
4);

$story = textarea(
    label: 'Tell me a story.',
    required: true
);

バリデーションメッセージをカスタマイズしたい場合は、文字列を渡すこともできます。

1$story = textarea(
2    label: 'Tell me a story.',
3    required: 'A story is required.'
4);

$story = textarea(
    label: 'Tell me a story.',
    required: 'A story is required.'
);

追加のバリデーション

最後に、追加のバリデーションロジックを実行したい場合は、validate引数にクロージャを渡します。

1$story = textarea(
2    label: 'Tell me a story.',
3    validate: fn (string $value) => match (true) {
4        strlen($value) < 250 => 'The story must be at least 250 characters.',
5        strlen($value) > 10000 => 'The story must not exceed 10,000 characters.',
6        default => null
7    }
8);

$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を返します。

1$story = textarea(
2    label: 'Tell me a story.',
3    validate: ['story' => 'required|max:10000']
4);

$story = textarea(
    label: 'Tell me a story.',
    validate: ['story' => 'required|max:10000']
);

Password

password関数はtext関数と似ていますが、ユーザーの入力はコンソールでタイプされるとマスクされます。これは、パスワードなどの機密情報を尋ねる際に便利です。

1use function Laravel\Prompts\password;
2 
3$password = password('What is your password?');

use function Laravel\Prompts\password;

$password = password('What is your password?');

プレースホルダーテキストや情報ヒントを含めることもできます。

1$password = password(
2    label: 'What is your password?',
3    placeholder: 'password',
4    hint: 'Minimum 8 characters.'
5);

$password = password(
    label: 'What is your password?',
    placeholder: 'password',
    hint: 'Minimum 8 characters.'
);

必須値

値の入力を必須にしたい場合は、required引数を渡してください。

1$password = password(
2    label: 'What is your password?',
3    required: true
4);

$password = password(
    label: 'What is your password?',
    required: true
);

バリデーションメッセージをカスタマイズしたい場合は、文字列を渡すこともできます。

1$password = password(
2    label: 'What is your password?',
3    required: 'The password is required.'
4);

$password = password(
    label: 'What is your password?',
    required: 'The password is required.'
);

追加のバリデーション

最後に、追加のバリデーションロジックを実行したい場合は、validate引数にクロージャを渡します。

1$password = password(
2    label: 'What is your password?',
3    validate: fn (string $value) => match (true) {
4        strlen($value) < 8 => 'The password must be at least 8 characters.',
5        default => null
6    }
7);

$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を返します。

1$password = password(
2    label: 'What is your password?',
3    validate: ['password' => 'min:8']
4);

$password = password(
    label: 'What is your password?',
    validate: ['password' => 'min:8']
);

確認

ユーザーに「はい/いいえ」の確認を求める必要がある場合は、confirm関数を使用できます。ユーザーは矢印キーを使用するか、yまたはnを押して応答を選択できます。この関数はtrueまたはfalseを返します。

1use function Laravel\Prompts\confirm;
2 
3$confirmed = confirm('Do you accept the terms?');

use function Laravel\Prompts\confirm;

$confirmed = confirm('Do you accept the terms?');

デフォルト値、「はい」と「いいえ」ラベルの文言のカスタマイズ、情報ヒントを含めることもできます。

1$confirmed = confirm(
2    label: 'Do you accept the terms?',
3    default: false,
4    yes: 'I accept',
5    no: 'I decline',
6    hint: 'The terms must be accepted to continue.'
7);

$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引数を渡すことで、ユーザーに「はい」を選択させることができます。

1$confirmed = confirm(
2    label: 'Do you accept the terms?',
3    required: true
4);

$confirmed = confirm(
    label: 'Do you accept the terms?',
    required: true
);

バリデーションメッセージをカスタマイズしたい場合は、文字列を渡すこともできます。

1$confirmed = confirm(
2    label: 'Do you accept the terms?',
3    required: 'You must accept the terms to continue.'
4);

$confirmed = confirm(
    label: 'Do you accept the terms?',
    required: 'You must accept the terms to continue.'
);

セレクト

ユーザーに事前定義された選択肢のセットから選択させる必要がある場合は、select関数を使用できます。

1use function Laravel\Prompts\select;
2 
3$role = select(
4    label: 'What role should the user have?',
5    options: ['Member', 'Contributor', 'Owner']
6);

use function Laravel\Prompts\select;

$role = select(
    label: 'What role should the user have?',
    options: ['Member', 'Contributor', 'Owner']
);

デフォルトの選択肢や情報ヒントを指定することもできます。

1$role = select(
2    label: 'What role should the user have?',
3    options: ['Member', 'Contributor', 'Owner'],
4    default: 'Owner',
5    hint: 'The role may be changed at any time.'
6);

$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引数に連想配列を渡して、値の代わりに対応するキーが返されるようにすることもできます。

1$role = select(
2    label: 'What role should the user have?',
3    options: [
4        'member' => 'Member',
5        'contributor' => 'Contributor',
6        'owner' => 'Owner',
7    ],
8    default: 'owner'
9);

$role = select(
    label: 'What role should the user have?',
    options: [
        'member' => 'Member',
        'contributor' => 'Contributor',
        'owner' => 'Owner',
    ],
    default: 'owner'
);

リストがスクロールし始める前に最大5つのオプションが表示されます。これはscroll引数を渡すことでカスタマイズできます。

1$role = select(
2    label: 'Which category would you like to assign?',
3    options: Category::pluck('name', 'id'),
4    scroll: 10
5);

$role = select(
    label: 'Which category would you like to assign?',
    options: Category::pluck('name', 'id'),
    scroll: 10
);

追加のバリデーション

他のプロンプト関数とは異なり、select関数は何も選択しないことが不可能なため、required引数を受け入れません。しかし、オプションを提示しつつ選択させたくない場合は、validate引数にクロージャを渡すことができます。

 1$role = select(
 2    label: 'What role should the user have?',
 3    options: [
 4        'member' => 'Member',
 5        'contributor' => 'Contributor',
 6        'owner' => 'Owner',
 7    ],
 8    validate: fn (string $value) =>
 9        $value === 'owner' && User::where('role', 'owner')->exists()
10            ? 'An owner already exists.'
11            : null
12);

$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関数を使用できます。

1use function Laravel\Prompts\multiselect;
2 
3$permissions = multiselect(
4    label: 'What permissions should be assigned?',
5    options: ['Read', 'Create', 'Update', 'Delete']
6);

use function Laravel\Prompts\multiselect;

$permissions = multiselect(
    label: 'What permissions should be assigned?',
    options: ['Read', 'Create', 'Update', 'Delete']
);

デフォルトの選択肢や情報ヒントを指定することもできます。

1use function Laravel\Prompts\multiselect;
2 
3$permissions = multiselect(
4    label: 'What permissions should be assigned?',
5    options: ['Read', 'Create', 'Update', 'Delete'],
6    default: ['Read', 'Create'],
7    hint: 'Permissions may be updated at any time.'
8);

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引数に連想配列を渡して、値の代わりに選択されたオプションのキーを返すこともできます。

 1$permissions = multiselect(
 2    label: 'What permissions should be assigned?',
 3    options: [
 4        'read' => 'Read',
 5        'create' => 'Create',
 6        'update' => 'Update',
 7        'delete' => 'Delete',
 8    ],
 9    default: ['read', 'create']
10);

$permissions = multiselect(
    label: 'What permissions should be assigned?',
    options: [
        'read' => 'Read',
        'create' => 'Create',
        'update' => 'Update',
        'delete' => 'Delete',
    ],
    default: ['read', 'create']
);

リストがスクロールし始める前に最大5つのオプションが表示されます。これはscroll引数を渡すことでカスタマイズできます。

1$categories = multiselect(
2    label: 'What categories should be assigned?',
3    options: Category::pluck('name', 'id'),
4    scroll: 10
5);

$categories = multiselect(
    label: 'What categories should be assigned?',
    options: Category::pluck('name', 'id'),
    scroll: 10
);

値の必須化

デフォルトでは、ユーザーは0個以上のオプションを選択できます。required引数を渡すことで、1つ以上のオプションを強制することができます。

1$categories = multiselect(
2    label: 'What categories should be assigned?',
3    options: Category::pluck('name', 'id'),
4    required: true
5);

$categories = multiselect(
    label: 'What categories should be assigned?',
    options: Category::pluck('name', 'id'),
    required: true
);

バリデーションメッセージをカスタマイズしたい場合は、required引数に文字列を指定します。

1$categories = multiselect(
2    label: 'What categories should be assigned?',
3    options: Category::pluck('name', 'id'),
4    required: 'You must select at least one category'
5);

$categories = multiselect(
    label: 'What categories should be assigned?',
    options: Category::pluck('name', 'id'),
    required: 'You must select at least one category'
);

追加のバリデーション

オプションを提示しつつ選択させたくない場合は、validate引数にクロージャを渡すことができます。

 1$permissions = multiselect(
 2    label: 'What permissions should the user have?',
 3    options: [
 4        'read' => 'Read',
 5        'create' => 'Create',
 6        'update' => 'Update',
 7        'delete' => 'Delete',
 8    ],
 9    validate: fn (array $values) => ! in_array('read', $values)
10        ? 'All users require the read permission.'
11        : null
12);

$permissions = multiselect(
    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
);

サジェスト

suggest関数は、選択可能な選択肢の自動補完を提供するために使用できます。ユーザーは自動補完のヒントに関係なく、任意の回答を提供できます。

1use function Laravel\Prompts\suggest;
2 
3$name = suggest('What is your name?', ['Taylor', 'Dayle']);

use function Laravel\Prompts\suggest;

$name = suggest('What is your name?', ['Taylor', 'Dayle']);

あるいは、suggest関数の第２引数としてクロージャを渡すこともできます。クロージャはユーザーが入力文字をタイプするたびに呼び出されます。クロージャは、それまでに入力された文字列を含む文字列パラメータを受け取り、自動補完用のオプションの配列を返す必要があります。

1$name = suggest(
2    label: 'What is your name?',
3    options: fn ($value) => collect(['Taylor', 'Dayle'])
4        ->filter(fn ($name) => Str::contains($name, $value, ignoreCase: true))
5)

$name = suggest(
    label: 'What is your name?',
    options: fn ($value) => collect(['Taylor', 'Dayle'])
        ->filter(fn ($name) => Str::contains($name, $value, ignoreCase: true))
)

プレースホルダーテキスト、デフォルト値、情報ヒントを含めることもできます。

1$name = suggest(
2    label: 'What is your name?',
3    options: ['Taylor', 'Dayle'],
4    placeholder: 'E.g. Taylor',
5    default: $user?->name,
6    hint: 'This will be displayed on your profile.'
7);

$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引数を渡してください。

1$name = suggest(
2    label: 'What is your name?',
3    options: ['Taylor', 'Dayle'],
4    required: true
5);

$name = suggest(
    label: 'What is your name?',
    options: ['Taylor', 'Dayle'],
    required: true
);

バリデーションメッセージをカスタマイズしたい場合は、文字列を渡すこともできます。

1$name = suggest(
2    label: 'What is your name?',
3    options: ['Taylor', 'Dayle'],
4    required: 'Your name is required.'
5);

$name = suggest(
    label: 'What is your name?',
    options: ['Taylor', 'Dayle'],
    required: 'Your name is required.'
);

追加のバリデーション

最後に、追加のバリデーションロジックを実行したい場合は、validate引数にクロージャを渡します。

1$name = suggest(
2    label: 'What is your name?',
3    options: ['Taylor', 'Dayle'],
4    validate: fn (string $value) => match (true) {
5        strlen($value) < 3 => 'The name must be at least 3 characters.',
6        strlen($value) > 255 => 'The name must not exceed 255 characters.',
7        default => null
8    }
9);

$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を返します。

1$name = suggest(
2    label: 'What is your name?',
3    options: ['Taylor', 'Dayle'],
4    validate: ['name' => 'required|min:3|max:255']
5);

$name = suggest(
    label: 'What is your name?',
    options: ['Taylor', 'Dayle'],
    validate: ['name' => 'required|min:3|max:255']
);

検索

ユーザーが選択できるオプションがたくさんある場合、search関数を使用すると、ユーザーは検索クエリを入力して結果をフィルタリングしてから、矢印キーを使用してオプションを選択できます。

1use function Laravel\Prompts\search;
2 
3$id = search(
4    label: 'Search for the user that should receive the mail',
5    options: fn (string $value) => strlen($value) > 0
6        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
7        : []
8);

use function Laravel\Prompts\search;

$id = search(
    label: 'Search for the user that should receive the mail',
    options: fn (string $value) => strlen($value) > 0
        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
        : []
);

クロージャは、ユーザーがそれまでにタイプしたテキストを受け取り、オプションの配列を返す必要があります。連想配列を返すと、選択されたオプションのキーが返され、そうでなければ値が返されます。

値を返すつもりの配列をフィルタリングする場合、配列が連想配列にならないように、array_values関数またはvalues Collectionメソッドを使用する必要があります。

1$names = collect(['Taylor', 'Abigail']);
2 
3$selected = search(
4    label: 'Search for the user that should receive the mail',
5    options: fn (string $value) => $names
6        ->filter(fn ($name) => Str::contains($name, $value, ignoreCase: true))
7        ->values()
8        ->all(),
9);

$names = collect(['Taylor', 'Abigail']);

$selected = search(
    label: 'Search for the user that should receive the mail',
    options: fn (string $value) => $names
        ->filter(fn ($name) => Str::contains($name, $value, ignoreCase: true))
        ->values()
        ->all(),
);

プレースホルダーテキストや情報ヒントを含めることもできます。

1$id = search(
2    label: 'Search for the user that should receive the mail',
3    placeholder: 'E.g. Taylor Otwell',
4    options: fn (string $value) => strlen($value) > 0
5        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
6        : [],
7    hint: 'The user will receive an email immediately.'
8);

$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::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    hint: 'The user will receive an email immediately.'
);

リストがスクロールし始める前に最大5つのオプションが表示されます。これはscroll引数を渡すことでカスタマイズできます。

1$id = search(
2    label: 'Search for the user that should receive the mail',
3    options: fn (string $value) => strlen($value) > 0
4        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
5        : [],
6    scroll: 10
7);

$id = search(
    label: 'Search for the user that should receive the mail',
    options: fn (string $value) => strlen($value) > 0
        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    scroll: 10
);

追加のバリデーション

追加のバリデーションロジックを実行したい場合は、validate引数にクロージャを渡すことができます。

 1$id = search(
 2    label: 'Search for the user that should receive the mail',
 3    options: fn (string $value) => strlen($value) > 0
 4        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
 5        : [],
 6    validate: function (int|string $value) {
 7        $user = User::findOrFail($value);
 8 
 9        if ($user->opted_out) {
10            return 'This user has opted-out of receiving mail.';
11        }
12    }
13);

$id = search(
    label: 'Search for the user that should receive the mail',
    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 'This user has opted-out of receiving mail.';
        }
    }
);

optionsクロージャが連想配列を返す場合、クロージャは選択されたキーを受け取ります。そうでなければ、選択された値を受け取ります。クロージャはエラーメッセージを返すか、バリデーションが通ればnullを返すことができます。

複数検索

検索可能なオプションが多数あり、ユーザーが複数の項目を選択する必要がある場合、multisearch関数を使用すると、ユーザーは検索クエリを入力して結果をフィルタリングしてから、矢印キーとスペースバーを使用してオプションを選択できます。

1use function Laravel\Prompts\multisearch;
2 
3$ids = multisearch(
4    'Search for the users that should receive the mail',
5    fn (string $value) => strlen($value) > 0
6        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
7        : []
8);

use function Laravel\Prompts\multisearch;

$ids = multisearch(
    'Search for the users that should receive the mail',
    fn (string $value) => strlen($value) > 0
        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
        : []
);

1$names = collect(['Taylor', 'Abigail']);
2 
3$selected = multisearch(
4    label: 'Search for the users that should receive the mail',
5    options: fn (string $value) => $names
6        ->filter(fn ($name) => Str::contains($name, $value, ignoreCase: true))
7        ->values()
8        ->all(),
9);

$names = collect(['Taylor', 'Abigail']);

$selected = multisearch(
    label: 'Search for the users that should receive the mail',
    options: fn (string $value) => $names
        ->filter(fn ($name) => Str::contains($name, $value, ignoreCase: true))
        ->values()
        ->all(),
);

プレースホルダーテキストや情報ヒントを含めることもできます。

1$ids = multisearch(
2    label: 'Search for the users that should receive the mail',
3    placeholder: 'E.g. Taylor Otwell',
4    options: fn (string $value) => strlen($value) > 0
5        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
6        : [],
7    hint: 'The user will receive an email immediately.'
8);

$ids = multisearch(
    label: 'Search for the users that should receive the mail',
    placeholder: 'E.g. Taylor Otwell',
    options: fn (string $value) => strlen($value) > 0
        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    hint: 'The user will receive an email immediately.'
);

リストがスクロールし始める前に最大5つのオプションが表示されます。これはscroll引数を指定することでカスタマイズできます。

1$ids = multisearch(
2    label: 'Search for the users that should receive the mail',
3    options: fn (string $value) => strlen($value) > 0
4        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
5        : [],
6    scroll: 10
7);

$ids = multisearch(
    label: 'Search for the users that should receive the mail',
    options: fn (string $value) => strlen($value) > 0
        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    scroll: 10
);

値の必須化

デフォルトでは、ユーザーは0個以上のオプションを選択できます。required引数を渡すことで、1つ以上のオプションを強制することができます。

1$ids = multisearch(
2    label: 'Search for the users that should receive the mail',
3    options: fn (string $value) => strlen($value) > 0
4        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
5        : [],
6    required: true
7);

$ids = multisearch(
    label: 'Search for the users that should receive the mail',
    options: fn (string $value) => strlen($value) > 0
        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    required: true
);

バリデーションメッセージをカスタマイズしたい場合は、required引数に文字列を指定することもできます。

1$ids = multisearch(
2    label: 'Search for the users that should receive the mail',
3    options: fn (string $value) => strlen($value) > 0
4        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
5        : [],
6    required: 'You must select at least one user.'
7);

$ids = multisearch(
    label: 'Search for the users that should receive the mail',
    options: fn (string $value) => strlen($value) > 0
        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    required: 'You must select at least one user.'
);

追加のバリデーション

追加のバリデーションロジックを実行したい場合は、validate引数にクロージャを渡すことができます。

 1$ids = multisearch(
 2    label: 'Search for the users that should receive the mail',
 3    options: fn (string $value) => strlen($value) > 0
 4        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
 5        : [],
 6    validate: function (array $values) {
 7        $optedOut = User::whereLike('name', '%a%')->findMany($values);
 8 
 9        if ($optedOut->isNotEmpty()) {
10            return $optedOut->pluck('name')->join(', ', ', and ').' have opted out.';
11        }
12    }
13);

$ids = multisearch(
    label: 'Search for the users that should receive the mail',
    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 ').' have opted out.';
        }
    }
);

一時停止

pause関数は、ユーザーに情報テキストを表示し、Enter / Returnキーを押して続行の意思を確認するのを待つために使用できます。

1use function Laravel\Prompts\pause;
2 
3pause('Press ENTER to continue.');

use function Laravel\Prompts\pause;

pause('Press ENTER to continue.');

バリデーション前の入力変換

バリデーションが行われる前にプロンプトの入力を変換したい場合があります。たとえば、指定された文字列から空白を削除したい場合などです。これを実現するために、多くのプロンプト関数はクロージャを受け入れるtransform引数を提供しています。

1$name = text(
2    label: 'What is your name?',
3    transform: fn (string $value) => trim($value),
4    validate: fn (string $value) => match (true) {
5        strlen($value) < 3 => 'The name must be at least 3 characters.',
6        strlen($value) > 255 => 'The name must not exceed 255 characters.',
7        default => null
8    }
9);

$name = text(
    label: 'What is your name?',
    transform: fn (string $value) => trim($value),
    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
    }
);

フォーム

多くの場合、追加のアクションを実行する前に情報を収集するために、複数のプロンプトを順番に表示することになります。form関数を使用して、ユーザーが完了するためのプロンプトのグループ化されたセットを作成できます。

1use function Laravel\Prompts\form;
2 
3$responses = form()
4    ->text('What is your name?', required: true)
5    ->password('What is your password?', validate: ['password' => 'min:8'])
6    ->confirm('Do you accept the terms?')
7    ->submit();

use function Laravel\Prompts\form;

$responses = form()
    ->text('What is your name?', required: true)
    ->password('What is your password?', validate: ['password' => 'min:8'])
    ->confirm('Do you accept the terms?')
    ->submit();

submitメソッドは、フォームのプロンプトからのすべての応答を含む数値インデックスの配列を返します。ただし、name引数を介して各プロンプトに名前を提供できます。名前が指定されると、名前付きプロンプトの応答はその名前を介してアクセスできます。

 1use App\Models\User;
 2use function Laravel\Prompts\form;
 3 
 4$responses = form()
 5    ->text('What is your name?', required: true, name: 'name')
 6    ->password(
 7        label: 'What is your password?',
 8        validate: ['password' => 'min:8'],
 9        name: 'password'
10    )
11    ->confirm('Do you accept the terms?')
12    ->submit();
13 
14User::create([
15    'name' => $responses['name'],
16    'password' => $responses['password'],
17]);

use App\Models\User;
use function Laravel\Prompts\form;

$responses = form()
    ->text('What is your name?', required: true, name: 'name')
    ->password(
        label: 'What is your password?',
        validate: ['password' => 'min:8'],
        name: 'password'
    )
    ->confirm('Do you accept the terms?')
    ->submit();

User::create([
    'name' => $responses['name'],
    'password' => $responses['password'],
]);

form関数を使用する主な利点は、ユーザーがCTRL + Uを使用してフォーム内の前のプロンプトに戻れることです。これにより、ユーザーはフォーム全体をキャンセルして再開することなく、間違いを修正したり選択を変更したりできます。

フォーム内のプロンプトをより細かく制御する必要がある場合は、プロンプト関数のいずれかを直接呼び出す代わりにaddメソッドを呼び出します。addメソッドには、ユーザーが提供したすべての以前の応答が渡されます。

 1use function Laravel\Prompts\form;
 2use function Laravel\Prompts\outro;
 3 
 4$responses = form()
 5    ->text('What is your name?', required: true, name: 'name')
 6    ->add(function ($responses) {
 7        return text("How old are you, {$responses['name']}?");
 8    }, name: 'age')
 9    ->submit();
10 
11outro("Your name is {$responses['name']} and you are {$responses['age']} years old.");

use function Laravel\Prompts\form;
use function Laravel\Prompts\outro;

$responses = form()
    ->text('What is your name?', required: true, name: 'name')
    ->add(function ($responses) {
        return text("How old are you, {$responses['name']}?");
    }, name: 'age')
    ->submit();

outro("Your name is {$responses['name']} and you are {$responses['age']} years old.");

情報メッセージ

note、info、warning、error、alert関数を使用して情報メッセージを表示できます。

1use function Laravel\Prompts\info;
2 
3info('Package installed successfully.');

use function Laravel\Prompts\info;

info('Package installed successfully.');

テーブル

table関数を使用すると、複数の行と列のデータを簡単に表示できます。必要なのは、列名とテーブルのデータを提供することだけです。

1use function Laravel\Prompts\table;
2 
3table(
4    headers: ['Name', 'Email'],
5    rows: User::all(['name', 'email'])->toArray()
6);

use function Laravel\Prompts\table;

table(
    headers: ['Name', 'Email'],
    rows: User::all(['name', 'email'])->toArray()
);

スピン

spin関数は、指定されたコールバックを実行中に、オプションのメッセージと共にスピナーを表示します。これは進行中のプロセスを示す役割を果たし、完了時にコールバックの結果を返します。

1use function Laravel\Prompts\spin;
2 
3$response = spin(
4    message: 'Fetching response...',
5    callback: fn () => Http::get('http://example.com')
6);

use function Laravel\Prompts\spin;

$response = spin(
    message: 'Fetching response...',
    callback: fn () => Http::get('http://example.com')
);

spin関数は、スピナーをアニメーション化するためにpcntl PHP拡張機能を必要とします。この拡張機能が利用できない場合、スピナーの静的なバージョンが表示されます。

プログレスバー

長時間のタスクでは、タスクの完了度をユーザーに知らせるプログレスバーを表示すると便利です。progress関数を使用すると、Laravelはプログレスバーを表示し、指定されたイテラブル値に対する各イテレーションでその進捗を進めます。

1use function Laravel\Prompts\progress;
2 
3$users = progress(
4    label: 'Updating users',
5    steps: User::all(),
6    callback: fn ($user) => $this->performTask($user)
7);

use function Laravel\Prompts\progress;

$users = progress(
    label: 'Updating users',
    steps: User::all(),
    callback: fn ($user) => $this->performTask($user)
);

progress関数はマップ関数のように機能し、コールバックの各イテレーションの戻り値を含む配列を返します。

コールバックはLaravel\Prompts\Progressインスタンスも受け取ることができ、各イテレーションでラベルとヒントを変更できます。

 1$users = progress(
 2    label: 'Updating users',
 3    steps: User::all(),
 4    callback: function ($user, $progress) {
 5        $progress
 6            ->label("Updating {$user->name}")
 7            ->hint("Created on {$user->created_at}");
 8 
 9        return $this->performTask($user);
10    },
11    hint: 'This may take some time.'
12);

$users = progress(
    label: 'Updating users',
    steps: User::all(),
    callback: function ($user, $progress) {
        $progress
            ->label("Updating {$user->name}")
            ->hint("Created on {$user->created_at}");

        return $this->performTask($user);
    },
    hint: 'This may take some time.'
);

プログレスバーの進め方をより手動で制御する必要がある場合があります。まず、プロセスが反復処理する合計ステップ数を定義します。次に、各項目を処理した後、advanceメソッドを介してプログレスバーを進めます。

 1$progress = progress(label: 'Updating users', steps: 10);
 2 
 3$users = User::all();
 4 
 5$progress->start();
 6 
 7foreach ($users as $user) {
 8    $this->performTask($user);
 9 
10    $progress->advance();
11}
12 
13$progress->finish();

$progress = progress(label: 'Updating users', steps: 10);

$users = User::all();

$progress->start();

foreach ($users as $user) {
    $this->performTask($user);

    $progress->advance();
}

$progress->finish();

ターミナルのクリア

clear関数を使用してユーザーのターミナルをクリアできます。

1use function Laravel\Prompts\clear;
2 
3clear();

use function Laravel\Prompts\clear;

clear();

ターミナルに関する考慮事項

ターミナルの幅

ラベル、オプション、またはバリデーションメッセージの長さがユーザーのターミナルの「列」数を超えると、自動的に切り捨てられて収まります。ユーザーがより狭いターミナルを使用している可能性がある場合は、これらの文字列の長さを最小限に抑えることを検討してください。通常、80文字のターミナルをサポートするための安全な最大長は74文字です。

ターミナルの高さ

scroll引数を受け入れるプロンプトの場合、設定された値は、バリデーションメッセージのスペースを含め、ユーザーのターミナルの高さに合わせて自動的に縮小されます。

非対応環境とフォールバック

Laravel PromptsはmacOS、Linux、およびWSLを使用するWindowsをサポートしています。Windows版PHPの制限により、現在、WSL以外でLaravel Promptsを使用することはできません。

このため、Laravel Promptsは、Symfony Console Question Helperなどの代替実装へのフォールバックをサポートしています。

LaravelフレームワークでLaravel Promptsを使用する場合、各プロンプトのフォールバックが設定されており、サポートされていない環境では自動的に有効になります。

フォールバック条件

Laravelを使用していない場合、またはフォールバック動作が使用されるタイミングをカスタマイズする必要がある場合は、PromptクラスのfallbackWhen静的メソッドにブール値を渡します。

1use Laravel\Prompts\Prompt;
2 
3Prompt::fallbackWhen(
4    ! $input->isInteractive() || windows_os() || app()->runningUnitTests()
5);

use Laravel\Prompts\Prompt;

Prompt::fallbackWhen(
    ! $input->isInteractive() || windows_os() || app()->runningUnitTests()
);

フォールバックの動作

Laravelを使用していない場合、またはフォールバックの動作をカスタマイズする必要がある場合は、各プロンプトクラスのfallbackUsing静的メソッドにクロージャを渡します。

 1use Laravel\Prompts\TextPrompt;
 2use Symfony\Component\Console\Question\Question;
 3use Symfony\Component\Console\Style\SymfonyStyle;
 4 
 5TextPrompt::fallbackUsing(function (TextPrompt $prompt) use ($input, $output) {
 6    $question = (new Question($prompt->label, $prompt->default ?: null))
 7        ->setValidator(function ($answer) use ($prompt) {
 8            if ($prompt->required && $answer === null) {
 9                throw new \RuntimeException(
10                    is_string($prompt->required) ? $prompt->required : 'Required.'
11                );
12            }
13 
14            if ($prompt->validate) {
15                $error = ($prompt->validate)($answer ?? '');
16 
17                if ($error) {
18                    throw new \RuntimeException($error);
19                }
20            }
21 
22            return $answer;
23        });
24 
25    return (new SymfonyStyle($input, $output))
26        ->askQuestion($question);
27});

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);
});

フォールバックは、各プロンプトクラスに対して個別に設定する必要があります。クロージャはプロンプトクラスのインスタンスを受け取り、プロンプトに適した型を返す必要があります。

序文

はじめに

アーキテクチャのコンセプト

基本

より深く知る

セキュリティ

データベース

Eloquent ORM

テスト

パッケージ

Prompts

製品

パッケージ

リソース