laravel-prompts

Laravel Prompts スキル

Laravel Prompts は、ブラウザーのようなプレースホルダーテキストやバリデーションなどの機能を備え、コマンドラインアプリケーションに美しく使いやすいフォームを追加するための PHP パッケージです。Laravel にプリインストールされており、macOS、Linux、WSL を使用する Windows に対応しています。

このスキルを使用するタイミング

次の場合にこのスキルを使用してください：

• インタラクティブなプロンプトを使う Laravel Artisan コマンドを作成する
• PHP でユーザーフレンドリーな CLI アプリケーションを作成する
• コマンドラインツールにフォームバリデーションを実装する
• コンソールコマンドにテキスト入力、選択メニュー、確認ダイアログを追加する
• CLI アプリケーションでプログレスバー、ローディングスピナー、テーブルを扱う
• プロンプトを使う Laravel コンソールコマンドをテストする
• シンプルなコンソール入力を、最新のバリデーション付きインタラクティブなプロンプトに置き換える

クイックリファレンス

基本的なテキスト入力

use function Laravel\Prompts\text;

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

// With placeholder and validation
$name = text(
    label: 'What is your name?',
    placeholder: 'E.g. Taylor Otwell',
    required: true,
    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
    }
);

パスワード入力

use function Laravel\Prompts\password;

$password = password(
    label: 'What is your password?',
    placeholder: 'password',
    hint: 'Minimum 8 characters.',
    required: true,
    validate: fn (string $value) => match (true) {
        strlen($value) < 8 => 'The password must be at least 8 characters.',
        default => null
    }
);

選択（単一選択）

use function Laravel\Prompts\select;

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

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

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

複数選択

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

// With validation
$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
);

確認ダイアログ

use function Laravel\Prompts\confirm;

// Simple yes/no
$confirmed = confirm('Do you accept the terms?');

// With custom labels
$confirmed = confirm(
    label: 'Do you accept the terms?',
    default: false,
    yes: 'I accept',
    no: 'I decline',
    hint: 'The terms must be accepted to continue.'
);

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

検索（検索可能な選択）

use function Laravel\Prompts\search;

$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.',
    scroll: 10
);

サジェスト（自動補完）

use function Laravel\Prompts\suggest;

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

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

複数ステップのフォーム

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

// Access named responses
echo $responses['name'];
echo $responses['password'];

// Dynamic forms with previous responses
$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();

プログレスバー

use function Laravel\Prompts\progress;

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

// With dynamic labels
$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.'
);

ローディングスピナー

use function Laravel\Prompts\spin;

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

主要な概念

入力の種類

Laravel Prompts は、さまざまな用途に応じた複数の入力タイプを提供します：

• text() - 任意のプレースホルダーとバリデーションを設定できる単一行テキスト入力
• textarea() - 長い内容を入力するための複数行テキスト入力
• password() - 機密データ用のマスクされたテキスト入力
• confirm() - はい／いいえの確認ダイアログ
• select() - 選択肢のリストからの単一選択
• multiselect() - リストから複数の項目を選択
• suggest() - 自動補完候補付きのテキスト入力
• search() - 動的な選択肢を使った検索可能な単一選択
• multisearch() - 検索可能な複数選択
• pause() - ユーザーが ENTER を押すまで実行を一時停止

出力の種類

入力を求めずに情報を表示する場合：

• info() - 情報メッセージを表示
• note() - 注記を表示
• warning() - 警告メッセージを表示
• error() - エラーメッセージを表示
• alert() - アラートメッセージを表示
• table() - 表形式のデータを表示

バリデーション

プロンプトをバリデーションする方法は 3 つあります：

1. クロージャーによるバリデーション：match 式を使ったカスタムロジック

   validate: fn (string $value) => match (true) {
       strlen($value) < 3 => 'Too short.',
       default => null
   }
   

2. Laravel のバリデーションルール：標準の Laravel バリデーション

   validate: ['email' => 'required|email|unique:users']
   

3. 必須フラグ：シンプルな必須チェック

   required: true
   

変換

transform パラメーターを使って、バリデーションの前に入力を変更します：

$name = text(
    label: 'What is your name?',
    transform: fn (string $value) => trim($value),
    validate: fn (string $value) => strlen($value) < 3
        ? 'The name must be at least 3 characters.'
        : null
);

ターミナルの機能

• スクロール：scroll パラメーターで表示項目数を設定します（デフォルト：5）
• ナビゲーション：矢印キー、j/k キー、または vim 形式のナビゲーションを使用します
• フォーム：フォーム内で CTRL + U を押すと、前のプロンプトに戻ります
• 幅：80 文字幅のターミナルでは、ラベルを 74 文字未満にします

リファレンスファイル

このスキルには、references/ に包括的なドキュメントが含まれています：

• other.md - Laravel Prompts の完全なドキュメント。以下が含まれます：
  • すべてのプロンプトタイプ（text、password、select、search など）
  • バリデーションの方法と例
  • 複数ステップ入力用のフォーム API
  • プログレスバーとローディングインジケーター
  • 情報メッセージ（info、warning、error、alert）
  • データ表示用のテーブル
  • コンソールコマンドのテスト方法
  • サポートされていない環境向けのフォールバック設定

詳しい情報が必要な場合は、view を使ってリファレンスファイルを参照してください。

このスキルの使用方法

初心者向け

基本的なプロンプトから始めましょう：

1. シンプルな入力には text() を使います
2. 必須フィールドには required: true を追加します
3. はい／いいえの質問には confirm() を試します
4. あらかじめ定義した選択肢には select() を使います

初心者向けコマンドの例：

$name = text('What is your name?', required: true);
$confirmed = confirm('Is this correct?');
if ($confirmed) {
    $this->info("Hello, {$name}!");
}

中級者向け

複数のプロンプトを組み合わせ、バリデーションを追加しましょう：

1. 複数ステップの入力には form() API を使います
2. クロージャーでカスタムバリデーションを追加します
3. データベース検索には search() を使います
4. 時間のかかる処理にはプログレスバーを実装します

中級者向けコマンドの例：

$responses = form()
    ->text('Name', required: true, name: 'name')
    ->select('Role', options: ['Member', 'Admin'], name: 'role')
    ->confirm('Create user?')
    ->submit();

if ($responses) {
    progress(
        label: 'Creating user',
        steps: 5,
        callback: fn () => sleep(1)
    );
}

上級ユーザー向け

高度な機能を活用します：

1. 以前の回答に基づく動的なフォームフィールド
2. Laravel のバリデーションルールによる複雑な検証
3. データベース連携に対応した、カスタムの検索可能なプロンプト
4. データ正規化のための変換関数
5. コマンドプロンプトのテスト戦略

高度なコマンドの例：

$responses = form()
    ->text('Email', validate: ['email' => 'required|email|unique:users'], name: 'email')
    ->add(function ($responses) {
        return search(
            label: 'Select manager',
            options: fn ($value) => User::where('email', 'like', "%{$value}%")
                ->where('email', '!=', $responses['email'])
                ->pluck('name', 'id')
                ->all()
        );
    }, name: 'manager_id')
    ->multiselect(
        label: 'Permissions',
        options: Permission::pluck('name', 'id'),
        validate: fn ($values) => count($values) === 0 ? 'Select at least one permission.' : null,
        name: 'permissions'
    )
    ->submit();

ナビゲーションのヒント

• 矢印キーまたはj/k - 選択／複数選択のオプションを移動します
• Space - 複数選択で項目を選択／選択解除します
• Enter - 選択を確定するか、入力を送信します
• CTRL + U - 前のプロンプトに戻ります（フォーム内）
• 入力して検索 - 検索／複数検索プロンプト内で使用します
• Tab - サジェストプロンプトで自動補完します

テスト

Laravel 組み込みのアサーションを使用して、プロンプトを含むコマンドをテストします：

use function Pest\Laravel\artisan;

test('user creation command', function () {
    artisan('users:create')
        ->expectsQuestion('What is your name?', 'Taylor Otwell')
        ->expectsQuestion('What is your email?', '[email protected]')
        ->expectsConfirmation('Create this user?', 'yes')
        ->expectsPromptsInfo('User created successfully!')
        ->assertExitCode(0);
});

test('displays warnings and errors', function () {
    artisan('report:generate')
        ->expectsPromptsWarning('This action cannot be undone')
        ->expectsPromptsError('Something went wrong')
        ->expectsPromptsTable(
            headers: ['Name', 'Email'],
            rows: [
                ['Taylor Otwell', '[email protected]'],
                ['Jason Beggs', '[email protected]'],
            ]
        )
        ->assertExitCode(0);
});

ベストプラクティス

設計ガイドライン

• ラベルは簡潔にします（80 桁のターミナルでは 74 文字未満）
• 追加のコンテキストには hint パラメーターを使用します
• 適切な場合は、適切な default 値を設定します
• 多数のオプションを含むリストでは scroll を設定します（デフォルト：5）

バリデーション戦略

• 必須フィールドには required: true を使用します
• 標準的なチェック（email、min/max など）には Laravel のバリデーションルールを適用します
• 複雑なビジネスロジックの検証にはクロージャーを使用します
• 明確で、対処方法がわかるエラーメッセージを提示します

ユーザーエクスペリエンス

• 期待される入力形式を示すプレースホルダーを追加します
• 破壊的な操作の前に pause() を使用します
• 2 秒を超える操作ではプログレスバーを表示します
• アクションの完了後に情報メッセージを表示します
• よりスムーズな操作のため、関連するプロンプトをフォームにまとめます

パフォーマンス

• 負荷の高いクエリを避けるため、長さのチェックを使って search() コールバックを使用します：

  options: fn (string $value) => strlen($value) > 0
      ? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
      : []
  

• ページネーションまたは上位 N 件のクエリでデータベースの結果を制限します
• 頻繁にアクセスされるオプションリストをキャッシュします
• HTTP リクエストや長時間かかる操作には spin() を使用します

よくあるパターン

ユーザー登録フロー

$responses = form()
    ->text('Name', required: true, name: 'name')
    ->text('Email', validate: ['email' => 'required|email|unique:users'], name: 'email')
    ->password('Password', validate: ['password' => 'required|min:8'], name: 'password')
    ->submit();

破壊的な操作の前の確認

$confirmed = confirm(
    label: 'Are you sure you want to delete all users?',
    default: false,
    hint: 'This action cannot be undone.'
);

if (! $confirmed) {
    $this->info('Operation cancelled.');
    return;
}

動的な複数ステップのフォーム

$responses = form()
    ->select('User type', options: ['Regular', 'Admin'], name: 'type')
    ->add(function ($responses) {
        if ($responses['type'] === 'Admin') {
            return password('Admin password', required: true);
        }
    }, name: 'admin_password')
    ->submit();

プログレス表示を伴うバッチ処理

$items = Item::all();

$results = progress(
    label: 'Processing items',
    steps: $items,
    callback: function ($item, $progress) {
        $progress->hint("Processing: {$item->name}");
        return $this->process($item);
    }
);

リソース

公式ドキュメント

• Laravel Prompts ドキュメント：https://laravel.com/docs/12.x/prompts
• Laravel コンソールテスト：https://laravel.com/docs/12.x/console-tests

プラットフォームのサポート

• サポート対象：macOS、Linux、WSL を使用した Windows
• フォールバック：サポート対象外の環境向けにフォールバック動作を設定します

注記

• Laravel Prompts は Laravel フレームワークにプリインストールされています
• Laravel のバリデーションルールに対応しており、簡単に統合できます
• インタラクティブ UI にターミナル制御コードを使用します
• すべてのプロンプトは、すぐに使用できる値を返します
• フォームでは CTRL + U を使って前のプロンプトに戻れます
• 即座にフィードバックを得られるよう、入力の変更ごとにバリデーションが実行されます
• プログレスバーは手動または自動で制御できます

更新

このスキルは Laravel Prompts の公式ドキュメントから生成されました。更新された情報を反映するには、Laravel ドキュメントサイトを再スクレイピングしてください。