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() - 显示表格数据

验证

验证提示有三种方式：

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
• 对标准检查（电子邮件、最小值/最大值等）应用 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 文档网站。