バージョン: 13.x

Prompts

Introduction
Installation
Available Prompts
- Text
- Textarea
- Number
- Password
- Confirm
- Select
- Multi-select
- Suggest
- Search
- Multi-search
- Pause
- Autocomplete
Transforming Input Before Validation
Forms
Informational Messages
Callouts
Tables
Spin
Progress Bar
Task
Stream
Terminal Title
Clearing the Terminal
Terminal Considerations
Unsupported Environments and Fallbacks
Testing

Introduction

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

Laravel プロンプトは、Artisan console commands でユーザー入力を受け入れるのに最適ですが、コマンドライン PHP プロジェクトでも使用できます。

Laravel プロンプトは、WSL を使用して macOS、Linux、および Windows をサポートします。詳細については、unsupported environments & fallbacks のドキュメントを参照してください。

Installation

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

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

composer require laravel/prompts

Available Prompts

Text

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 Values

値を入力する必要がある場合は、required 引数を渡すことができます。

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

検証メッセージをカスタマイズしたい場合は、文字列を渡すこともできます。

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

Additional Validation

最後に、追加の検証ロジックを実行したい場合は、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 の validator の機能を活用することもできます。これを行うには、属性の名前と必要な検証ルールを含む配列を validate 引数に指定します。

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

Textarea

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

use function Laravel\Prompts\textarea;

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

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

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

Required Values

値を入力する必要がある場合は、required 引数を渡すことができます。

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

検証メッセージをカスタマイズしたい場合は、文字列を渡すこともできます。

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

Additional Validation

最後に、追加の検証ロジックを実行したい場合は、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 を返す場合があります。

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

Number

number 関数は、ユーザーに指定された質問を表示し、数値入力を受け入れて、それを返します。 number 関数を使用すると、ユーザーは上下の矢印キーを使用して数値を操作できます。

use function Laravel\Prompts\number;

$number = number('How many copies would you like?');

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

$name = number(
    label: 'How many copies would you like?',
    placeholder: '5',
    default: 1,
    hint: 'This will be determine how many copies to create.'
);

Required Values

値を入力する必要がある場合は、required 引数を渡すことができます。

$copies = number(
    label: 'How many copies would you like?',
    required: true
);

検証メッセージをカスタマイズしたい場合は、文字列を渡すこともできます。

$copies = number(
    label: 'How many copies would you like?',
    required: 'A number of copies is required.'
);

Additional Validation

最後に、追加の検証ロジックを実行したい場合は、validate 引数にクロージャを渡すことができます。

$copies = number(
    label: 'How many copies would you like?',
    validate: fn (?int $value) => match (true) {
        $value < 1 => 'At least one copy is required.',
        $value > 100 => 'You may not create more than 100 copies.',
        default => null
    }
);

クロージャは入力された値を受け取り、エラーメッセージを返すか、検証に合格した場合は null を返す場合があります。

$copies = number(
    label: 'How many copies would you like?',
    validate: ['copies' => 'required|integer|min:1|max:100']
);

Password

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 Values

値を入力する必要がある場合は、required 引数を渡すことができます。

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

検証メッセージをカスタマイズしたい場合は、文字列を渡すこともできます。

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

Additional Validation

最後に、追加の検証ロジックを実行したい場合は、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 を返す場合があります。

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

Confirm

ユーザーに「はいまたはいいえ」の確認を求める必要がある場合は、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.'
);

Requiring "Yes"

必要に応じて、required 引数を渡して、ユーザーに「はい」を選択するよう要求することもできます。

$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

ユーザーに事前定義された一連の選択肢から選択する必要がある場合は、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
);

Secondary Information

info 引数は、現在強調表示されているオプションに関する追加情報を表示するために使用できます。クロージャーが提供されると、現在強調表示されているオプションの値を受け取り、文字列または null を返す必要があります。

$role = select(
    label: 'What role should the user have?',
    options: [
        'member' => 'Member',
        'contributor' => 'Contributor',
        'owner' => 'Owner',
    ],
    info: fn (string $value) => match ($value) {
        'member' => 'Can view and comment.',
        'contributor' => 'Can view, comment, and edit.',
        'owner' => 'Full access to all resources.',
        default => null,
    }
);

情報が強調表示されたオプションに依存しない場合は、静的文字列を info 引数に渡すこともできます。

$role = select(
    label: 'What role should the user have?',
    options: ['Member', 'Contributor', 'Owner'],
    info: 'The role may be changed at any time.'
);

Additional Validation

他のプロンプト関数とは異なり、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 を返す場合があります。

Multi-select

ユーザーが複数のオプションを選択できるようにする必要がある場合は、multiselect 関数を使用できます。

use function Laravel\Prompts\multiselect;

$permissions = multiselect(
    label: 'What permissions should be assigned?',
    options: ['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']
);

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

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

Secondary Information

$permissions = multiselect(
    label: 'What permissions should be assigned?',
    options: [
        'read' => 'Read',
        'create' => 'Create',
        'update' => 'Update',
        'delete' => 'Delete',
    ],
    info: fn (string $value) => match ($value) {
        'read' => 'View resources and their properties.',
        'create' => 'Create new resources.',
        'update' => 'Modify existing resources.',
        'delete' => 'Permanently remove resources.',
        default => null,
    }
);

Requiring a Value

デフォルトでは、ユーザーは 0 個以上のオプションを選択できます。代わりに、required 引数を渡して 1 つ以上のオプションを適用できます。

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

検証メッセージをカスタマイズしたい場合は、required 引数に文字列を指定できます。

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

Additional Validation

オプションを提示する必要があるが、それが選択されないようにする場合は、validate 引数にクロージャーを渡すことができます。

$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

suggest 関数を使用すると、可能な選択肢のオートコンプリートを提供できます。ユーザーは、オートコンプリートのヒントに関係なく、任意の回答を入力できます。

use function Laravel\Prompts\suggest;

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

あるいは、suggest 関数の 2 番目の引数としてクロージャを渡すこともできます。クロージャは、ユーザーが入力文字を入力するたびに呼び出されます。クロージャは、これまでのユーザーの入力を含む文字列パラメータを受け入れ、オートコンプリートのオプションの配列を返す必要があります。

$name = suggest(
    label: 'What is your name?',
    options: 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.'
);

Secondary Information

$name = suggest(
    label: 'What is your name?',
    options: ['Taylor', 'Dayle'],
    info: fn (string $value) => match ($value) {
        'Taylor' => 'Administrator',
        'Dayle' => 'Contributor',
        default => null,
    }
);

Required Values

値を入力する必要がある場合は、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.'
);

Additional Validation

最後に、追加の検証ロジックを実行したい場合は、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 を返す場合があります。

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

Search

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

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 メソッドを使用する必要があります。

$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(),
);

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

$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 引数を渡すことでこれをカスタマイズできます。

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

Secondary Information

$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()
        : [],
    info: fn (int $userId) => User::find($userId)?->email
);

Additional Validation

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

$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 を返す場合があります。

Multi-search

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

use function Laravel\Prompts\multisearch;

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

クロージャは、ユーザーがこれまでに入力したテキストを受け取り、オプションの配列を返す必要があります。連想配列を返す場合は、選択したオプションのキーが返されます。それ以外の場合は、代わりに値が返されます。

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

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

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

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

$ids = multisearch(
    label: 'Search for users who 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 引数を指定してこれをカスタマイズできます。

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

Secondary Information

$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()
        : [],
    info: fn (int $userId) => User::find($userId)?->email
);

Requiring a Value

デフォルトでは、ユーザーは 0 個以上のオプションを選択できます。代わりに、required 引数を渡して 1 つ以上のオプションを適用できます。

$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 引数に文字列を指定することもできます。

$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.'
);

Additional Validation

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

$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.';
        }
    }
);

options クロージャが連想配列を返す場合、クロージャは選択されたキーを受け取ります。それ以外の場合は、選択された値を受け取ります。クロージャはエラーメッセージを返すか、検証に合格した場合は null を返す場合があります。

Pause

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

use function Laravel\Prompts\pause;

pause('Press ENTER to continue.');

Autocomplete

autocomplete 関数を使用すると、可能な選択肢に対するインラインオートコンプリートを提供できます。ユーザーが入力すると、入力に一致する候補がゴーストテキストとして表示され、Tab または右矢印キーを押すことで受け入れられます。

use function Laravel\Prompts\autocomplete;

$name = autocomplete(
    label: 'What is your name?',
    options: ['Taylor', 'Dayle', 'Jess', 'Nuno', 'Tim']
);

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

$name = autocomplete(
    label: 'What is your name?',
    options: ['Taylor', 'Dayle', 'Jess', 'Nuno', 'Tim'],
    placeholder: 'E.g. Taylor',
    default: $user?->name,
    hint: 'Use tab to accept, up/down to cycle.'
);

Dynamic Options

クロージャを渡して、ユーザーの入力に基づいてオプションを動的に生成することもできます。クロージャはユーザーが文字を入力するたびに呼び出され、オートコンプリートのオプションの配列を返す必要があります。

$file = autocomplete(
    label: 'Which file?',
    options: fn (string $value) => collect($files)
        ->filter(fn ($file) => str_starts_with(strtolower($file), strtolower($value)))
        ->values()
        ->all(),
);

Required Values

値を入力する必要がある場合は、required 引数を渡すことができます。

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

検証メッセージをカスタマイズしたい場合は、文字列を渡すこともできます。

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

Additional Validation

最後に、追加の検証ロジックを実行したい場合は、validate 引数にクロージャを渡すことができます。

$name = autocomplete(
    label: 'What is your name?',
    options: ['Taylor', 'Dayle', 'Jess', 'Nuno', 'Tim'],
    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 を返す場合があります。

Transforming Input Before Validation

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

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

Forms

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

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 引数を介して各プロンプトに名前を指定できます。名前を指定すると、その名前を介して、指定されたプロンプトの応答にアクセスできます。

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 を使用してフォーム内の前のプロンプトに戻ることができることです。これにより、ユーザーはフォーム全体をキャンセルして再起動することなく、間違いを修正したり選択内容を変更したりすることができます。

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

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

$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.");

Informational Messages

note、info、warning、error、および alert 関数は、情報メッセージを表示するために使用できます。

use function Laravel\Prompts\info;

info('Package installed successfully.');

Callouts

callout 関数は、ラベルとコンテンツを含むボックス化されたメッセージを表示します。コールアウトは、デプロイメントの概要、エラーの詳細、ステータスの更新など、目立たせるべき重要な情報を表示するのに役立ちます。

use function Laravel\Prompts\callout;

callout(
    label: 'Environment Configured',
    content: 'Your application is running in production mode with 4 workers.',
);

type 引数として warning または error を渡すと、コールアウトの視覚的なスタイルを変更できます。

callout(
    label: 'Deprecation Notice',
    content: 'The `--prefer-stable` flag will be removed in v4.0. Use `--stability=stable` instead.',
    type: 'warning',
);

callout(
    label: 'Database Connection Failed',
    content: 'Could not connect to MySQL on 127.0.0.1:3306.',
    type: 'error',
);

info 引数はコールアウトにフッター行を追加します。これは、ID やタイムスタンプなどのメタデータを表示するのに役立ちます。

callout(
    label: 'Deployment Summary',
    content: 'Your application was deployed to production.',
    info: 'deploy-id: d4f8a2c',
);

Rich Content

文字列の代わりに、文字列と要素の配列を渡して、リッチで構造化されたコールアウトを作成できます。Element クラスは、見出し、箇条書きリスト、番号付きリスト、キーと値のリスト、およびリンクを作成するためのファクトリメソッドを提供します。

use Laravel\Prompts\Elements\Element;

use function Laravel\Prompts\callout;

callout('Deployment Summary', [
    'Your application was deployed to production at 2024-03-15 14:32 UTC.',
    Element::heading('What Changed'),
    Element::bulletedList([
        'Migrated 3 pending database migrations',
        'Cleared and rebuilt route cache',
        'Restarted 4 queue workers',
    ]),
    Element::heading('Next Steps'),
    Element::numberedList([
        'Verify the health check endpoint at /up',
        'Monitor error rates for the next 15 minutes',
        'Confirm background jobs are processing',
    ]),
]);

Element::keyValueList を使用して、ラベル付きデータを表示することもできます。

callout('Database Connection Failed', [
    'Could not connect to the database server.',
    Element::keyValueList([
        'Host' => '127.0.0.1',
        'Port' => '3306',
        'Database' => 'forge',
        'Status' => 'Connection refused',
    ]),
], type: 'error');

Element::link メソッドは、OSC 8 をサポートするターミナルでクリック可能なハイパーリンクを作成します。URL だけを渡すこともできますし、カスタムラベル付きの URL を渡すこともできます:

callout('Server Health Check', [
    'Multiple services are reporting degraded performance.',
    Element::heading('Affected Services'),
    'Look here: '.Element::link('https://example.com/health', 'Health Dashboard'),
    Element::link('https://example.com/health'),
]);

ラベルを指定しない場合は、URL 自体がリンクテキストとして表示されます。

Tables

table 関数を使用すると、複数の行と列のデータを簡単に表示できます。テーブルの列名とデータを指定するだけです。

use function Laravel\Prompts\table;

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

Spin

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

use function Laravel\Prompts\spin;

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

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

Progress Bars

長時間実行されるタスクの場合は、タスクの完了度をユーザーに知らせる進行状況バーを表示すると便利です。 progress 関数を使用すると、Laravel は進行状況バーを表示し、指定された反復可能な値を超えて反復ごとに進行状況を進めます。

use function Laravel\Prompts\progress;

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

progress 関数はマップ関数のように動作し、コールバックの各反復の戻り値を含む配列を返します。

コールバックは Laravel\Prompts\Progress インスタンスも受け入れることができるため、各反復でラベルとヒントを変更できます。

$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 メソッドを使用して進行状況バーを進めます。

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

$users = User::all();

$progress->start();

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

    $progress->advance();
}

$progress->finish();

Task

task 関数は、特定のコールバックの実行中に、スピナーとスクロールするライブ出力領域を備えたラベル付きタスクを表示します。これは、依存関係のインストールやデプロイメントスクリプトなどの長時間実行プロセスをラップするのに最適で、何が起こっているかをリアルタイムで把握できます。

use function Laravel\Prompts\task;

task(
    label: 'Installing dependencies',
    callback: function ($logger) {
        // Long-running process...
    }
);

コールバックは、タスクの出力領域にログ行、ステータスメッセージ、およびストリームテキストを表示するために使用できる Logger インスタンスを受け取ります。

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

Logging Lines

line メソッドは、単一のログ行をタスクのスクロール出力領域に書き込みます。

task(
    label: 'Installing dependencies',
    callback: function ($logger) {
        $logger->line('Resolving packages...');
        // ...
        $logger->line('Downloading laravel/framework');
        // ...
    }
);

Status Messages

success、warning、および error メソッドを使用してステータスメッセージを表示できます。これらは、スクロールするログ領域の上に安定した強調表示されたメッセージとして表示されます。

task(
    label: 'Deploying application',
    callback: function ($logger) {
        $logger->line('Pulling latest changes...');
        // ...
        $logger->success('Changes pulled!');

        $logger->line('Running migrations...');
        // ...
        $logger->warning('No new migrations to run.');

        $logger->line('Clearing cache...');
        // ...
        $logger->success('Cache cleared!');
    }
);

Updating the Label

label メソッドを使用すると、タスクの実行中にタスクのラベルを更新できます。

task(
    label: 'Starting deployment...',
    callback: function ($logger) {
        $logger->label('Pulling latest changes...');
        // ...
        $logger->label('Running migrations...');
        // ...
        $logger->label('Clearing cache...');
        // ...
    }
);

Displaying a Sub-Label

subLabel メソッドは、タスクのメインラベルの下に薄暗い線を表示します。これは、現在進行中のステップなどの一時的なステータスを伝えるのに役立ちます。サブラベルをクリアするには、空の文字列を渡します。

task(
    label: 'Deploying',
    callback: function ($logger) {
        $logger->subLabel('Building assets...');
        // ...
        $logger->subLabel('Running migrations...');
        // ...
        $logger->subLabel('');
    }
);

subLabel 引数を介して初期サブラベルを指定することもできます。

task(
    label: 'Deploying',
    callback: function ($logger) {
        // ...
    },
    subLabel: 'Preparing...'
);

Streaming Text

AI が生成した応答など、段階的に出力を生成するプロセスの場合、partial メソッドを使用すると、テキストを単語ごとまたはチャンクごとにストリーミングできます。ストリームが完了したら、commitPartial を呼び出して出力を完成させます。

task(
    label: 'Generating response...',
    callback: function ($logger) {
        foreach ($words as $word) {
            $logger->partial($word . ' ');
        }

        $logger->commitPartial();
    }
);

Customizing the Output Limit

デフォルトでは、タスクは最大 10 行のスクロール出力を表示します。これは、limit 引数を使用してカスタマイズできます。

task(
    label: 'Installing dependencies',
    callback: function ($logger) {
        // ...
    },
    limit: 20
);

Keeping the Summary

デフォルトでは、コールバックが終了するとタスクの出力は消去されます。タスクの完了後にステータスメッセージを画面に表示したままにしたい場合は、keepSummary 引数を渡すことができます。

task(
    label: 'Deploying',
    callback: function ($logger) {
        $logger->success('Assets built');
        // ...
        $logger->success('Migrations complete');
    },
    keepSummary: true,
);

Stream

stream 関数は、端末にストリーミングされるテキストを表示します。これは、AI によって生成されたコンテンツや段階的に到着するテキストの表示に最適です。

use function Laravel\Prompts\stream;

$stream = stream();

foreach ($words as $word) {
    $stream->append($word . ' ');
    usleep(25_000); // Simulate delay between chunks...
}

$stream->close();

append メソッドはテキストをストリームに追加し、段階的なフェードイン効果でレンダリングします。すべてのコンテンツがストリーミングされたら、close メソッドを呼び出して出力を終了し、カーソルを復元します。

Terminal Title

title 関数は、ユーザーの端末ウィンドウまたはタブのタイトルを更新します。

use function Laravel\Prompts\title;

title('Installing Dependencies');

ターミナルのタイトルをデフォルトにリセットするには、空の文字列を渡します。

title('');

Clearing the Terminal

clear 関数は、ユーザーの端末をクリアするために使用できます。

use function Laravel\Prompts\clear;

clear();

Terminal Considerations

Terminal Width

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

Terminal Height

scroll 引数を受け入れるプロンプトの場合、構成された値は、検証メッセージ用のスペースを含め、ユーザーの端末の高さに合わせて自動的に縮小されます。

Unsupported Environments and Fallbacks

Laravel プロンプトは、WSL を使用して macOS、Linux、および Windows をサポートします。 PHP の Windows バージョンの制限のため、現在、WSL 以外の Windows 上で Laravel プロンプトを使用することはできません。

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

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

Fallback Conditions

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

use Laravel\Prompts\Prompt;

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

Fallback Behavior

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

フォールバックは、プロンプトクラスごとに個別に構成する必要があります。クロージャはプロンプトクラスのインスタンスを受け取り、プロンプトの適切なタイプを返さなければなりません。

Testing

Laravel には、コマンドが予期したプロンプトメッセージを表示するかどうかをテストするためのさまざまな方法が用意されています。

test('report generation', function () {
    $this->artisan('report:generate')
        ->expectsPromptsInfo('Welcome to the application!')
        ->expectsPromptsWarning('This action cannot be undone')
        ->expectsPromptsError('Something went wrong')
        ->expectsPromptsAlert('Important notice!')
        ->expectsPromptsIntro('Starting process...')
        ->expectsPromptsOutro('Process completed!')
        ->expectsPromptsTable(
            headers: ['Name', 'Email'],
            rows: [
                ['Taylor Otwell', '[email protected]'],
                ['Jason Beggs', '[email protected]'],
            ]
        )
        ->assertExitCode(0);
});

public function test_report_generation(): void
{
    $this->artisan('report:generate')
        ->expectsPromptsInfo('Welcome to the application!')
        ->expectsPromptsWarning('This action cannot be undone')
        ->expectsPromptsError('Something went wrong')
        ->expectsPromptsAlert('Important notice!')
        ->expectsPromptsIntro('Starting process...')
        ->expectsPromptsOutro('Process completed!')
        ->expectsPromptsTable(
            headers: ['Name', 'Email'],
            rows: [
                ['Taylor Otwell', '[email protected]'],
                ['Jason Beggs', '[email protected]'],
            ]
        )
        ->assertExitCode(0);
}

Introduction​

Installation​

Available Prompts​

Text​

Required Values​

Additional Validation​

Textarea​

Required Values​

Additional Validation​

Number​

Required Values​

Additional Validation​

Password​

Required Values​

Additional Validation​

Confirm​

Requiring "Yes"​

Select​

Secondary Information​

Additional Validation​

Multi-select​

Secondary Information​

Requiring a Value​

Additional Validation​

Suggest​

Secondary Information​

Required Values​

Additional Validation​

Search​

Secondary Information​

Additional Validation​

Multi-search​

Secondary Information​

Requiring a Value​

Additional Validation​

Pause​

Autocomplete​

Dynamic Options​

Required Values​

Additional Validation​

Transforming Input Before Validation​

Forms​

Informational Messages​

Callouts​

Rich Content​

Tables​

Spin​

Progress Bars​

Task​

Logging Lines​

Status Messages​

Updating the Label​

Displaying a Sub-Label​

Streaming Text​

Customizing the Output Limit​

Keeping the Summary​

Stream​

Terminal Title​

Clearing the Terminal​

Terminal Considerations​

Terminal Width​

Terminal Height​

Unsupported Environments and Fallbacks​

Fallback Conditions​

Fallback Behavior​

Testing​

Introduction

Installation

Available Prompts

Text

Required Values

Additional Validation

Textarea

Required Values

Additional Validation

Number

Required Values

Additional Validation

Password

Required Values

Additional Validation

Confirm

Requiring "Yes"

Select

Secondary Information

Additional Validation

Multi-select

Secondary Information

Requiring a Value

Additional Validation

Suggest

Secondary Information

Required Values

Additional Validation

Search

Secondary Information

Additional Validation

Multi-search

Secondary Information

Requiring a Value

Additional Validation

Pause

Autocomplete

Dynamic Options

Required Values

Additional Validation

Transforming Input Before Validation

Forms

Informational Messages

Callouts

Rich Content

Tables

Spin

Progress Bars

Task

Logging Lines

Status Messages

Updating the Label

Displaying a Sub-Label

Streaming Text

Customizing the Output Limit

Keeping the Summary

Stream

Terminal Title

Clearing the Terminal

Terminal Considerations

Terminal Width

Terminal Height

Unsupported Environments and Fallbacks

Fallback Conditions

Fallback Behavior

Testing