Laravel 10.x Prompts

イントロダクション

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

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: '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']
);

5選択肢を超えると、選択肢がリスト表示されます。scroll引数を渡し、カスタマイズ可能です。

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

必須値

デフォルトで、ユーザーは0個以上の選択肢を選択できます。required引数を渡せば、代わりに1つ以上の選択肢を強制できます。

$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関数の第2引数にクロージャを渡すこともできます。クロージャはユーザーが入力文字をタイプするたびに呼び出されます。クロージャは文字列パラメータにこれまでのユーザー入力を受け取り、オートコンプリート用の選択肢配列を返す必要があります。

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

5選択肢を超えると、選択肢がリスト表示されます。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を返してください。

情報メッセージ

noteinfowarningerroralert関数は、情報メッセージを表示するために使用します。

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関数でスピナーをアニメーションするために、pcntl PHP拡張モジュールが必要です。この拡張モジュールが利用できない場合は、代わりに静的なスピナーが表示されます。

ターミナルの考察

ターミナルの横幅

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

ターミナルの高さ

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

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

ドキュメント章別ページ

ヘッダー項目移動

注目:アイコン:ページ内リンク設置(リンクがないヘッダーへの移動では、リンクがある以前のヘッダーのハッシュをURLへ付加します。

移動

クリックで即時移動します。

設定

適用ボタンクリック後に、全項目まとめて適用されます。

カラーテーマ
和文指定 Pagination
和文指定 Scaffold
Largeスクリーン表示幅
インデント
本文フォント
コードフォント
フォント適用確認

フォントの指定フィールドから、フォーカスが外れると、当ブロックの内容に反映されます。EnglishのDisplayもPreviewしてください。

フォント設定時、表示に不具合が出た場合、当サイトのクッキーを削除してください。

バックスラッシュを含むインライン\Code\Blockの例です。

以下はコードブロックの例です。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * ユーザに関連する電話レコードを取得
     */
    public function phone()
    {
        return $this->hasOne('App\Phone');
    }
}

設定を保存する前に、表示が乱れないか必ず確認してください。CSSによるフォントファミリー指定の知識がない場合は、フォントを変更しないほうが良いでしょう。

キーボード・ショートカット

オープン操作

PDC

ページ(章)移動の左オフキャンバスオープン

HA

ヘッダー移動モーダルオープン

MS

移動/設定の右オフキャンバスオープン

ヘッダー移動

T

最初のヘッダーへ移動

E

最後のヘッダーへ移動

NJ

次ヘッダー(H2〜H4)へ移動

BK

前ヘッダー(H2〜H4)へ移動

その他

?

このヘルプページ表示
閉じる