提示

• 介绍
• 安装
• 可用的提示
  • 文本
  • 多行文本
  • 数字
  • 密码
  • 确认
  • 选择
  • 多选
  • 建议
  • 搜索
  • 多重搜索
  • 暂停
  • 自动补全
• 在验证前转换输入
• 表单
• 信息消息
• 表格
• 旋转
• 进度条
• 任务
• 流
• 终端标题
• 通知
• 清除终端
• 终端注意事项
• 不支持的环境和回退
• 测试

介绍

Laravel 提示 是一个 PHP 包，用于在命令行应用程序中添加美观且用户友好的表单，具有类似浏览器的功能，包括占位符文本和验证。

Laravel 提示非常适合在 Artisan 控制台命令 中接受用户输入，但也可以在任何命令行 PHP 项目中使用。

注意

Laravel 提示支持 macOS、Linux 和 Windows 的 WSL。有关更多信息，请参阅我们的关于不支持的环境和回退的文档。

安装

Laravel 提示已经包含在最新版本的 Laravel 中。

您也可以通过 Composer 包管理器将 Laravel 提示安装到其他 PHP 项目中：

composer require laravel/prompts

可用的提示

文本

text 函数将提示用户给定的问题，接受他们的输入，然后返回它：

use function Laravel\Prompts\text;

$name = text('你叫什么名字？');

您还可以包括占位符文本、默认值和信息提示：

$name = text(
    label: '你叫什么名字？',
    placeholder: '例如 Taylor Otwell',
    default: $user?->name,
    hint: '这将显示在您的个人资料上。'
);

必填值

如果您需要输入值，可以传递 required 参数：

$name = text(
    label: '你叫什么名字？',
    required: true
);

如果您想自定义验证消息，也可以传递一个字符串：

$name = text(
    label: '你叫什么名字？',
    required: '您的名字是必填项。'
);

额外验证

最后，如果您想执行额外的验证逻辑，可以将闭包传递给 validate 参数：

$name = text(
    label: '你叫什么名字？',
    validate: fn (string $value) => match (true) {
        strlen($value) < 3 => '名字必须至少有 3 个字符。',
        strlen($value) > 255 => '名字不能超过 255 个字符。',
        default => null
    }
);

闭包将接收已输入的值，并可以返回错误消息，或者如果验证通过则返回 null。

或者，您可以利用 Laravel 的 validator。为此，请提供一个包含属性名称和所需验证规则的数组给 validate 参数：

$name = text(
    label: '你叫什么名字？',
    validate: ['name' => 'required|max:255|unique:users']
);

多行文本

textarea 函数将提示用户给定的问题，通过多行文本区域接受他们的输入，然后返回它：

use function Laravel\Prompts\textarea;

$story = textarea('给我讲个故事。');

您还可以包括占位符文本、默认值和信息提示：

$story = textarea(
    label: '给我讲个故事。',
    placeholder: '这是一个关于...的故事',
    hint: '这将显示在您的个人资料上。'
);

必填值

如果您需要输入值，可以传递 required 参数：

$story = textarea(
    label: '给我讲个故事。',
    required: true
);

如果您想自定义验证消息，也可以传递一个字符串：

$story = textarea(
    label: '给我讲个故事。',
    required: '需要一个故事。'
);

额外验证

最后，如果您想执行额外的验证逻辑，可以将闭包传递给 validate 参数：

$story = textarea(
    label: '给我讲个故事。',
    validate: fn (string $value) => match (true) {
        strlen($value) < 250 => '故事必须至少有 250 个字符。',
        strlen($value) > 10000 => '故事不能超过 10,000 个字符。',
        default => null
    }
);

闭包将接收已输入的值，并可以返回错误消息，或者如果验证通过则返回 null。

或者，您可以利用 Laravel 的 validator。为此，请提供一个包含属性名称和所需验证规则的数组给 validate 参数：

$story = textarea(
    label: '给我讲个故事。',
    validate: ['story' => 'required|max:10000']
);

数字

number 函数将使用给定的问题提示用户，接受其数字输入，然后将其返回。number 函数允许用户使用上下箭头键来调整数值：

use function Laravel\Prompts\number;

$number = number('您需要多少份副本？');

您还可以包含占位符文本、默认值和信息提示：

$name = number(
    label: '您需要多少份副本？',
    placeholder: '5',
    default: 1,
    hint: '这将决定要创建多少份副本。'
);

必填值

如果需要用户必须输入一个值，可以传递 required 参数：

$copies = number(
    label: '您需要多少份副本？',
    required: true
);

如果您想自定义验证消息，也可以传递一个字符串：

$copies = number(
    label: '您需要多少份副本？',
    required: '必须提供副本数量。'
);

附加验证

最后，如果您希望执行额外的验证逻辑，可以向 validate 参数传递一个闭包：

$copies = number(
    label: '您需要多少份副本？',
    validate: fn (?int $value) => match (true) {
        $value < 1 => '至少需要一份副本。',
        $value > 100 => '副本数量不能超过 100 份。',
        default => null
    }
);

闭包将接收已输入的值，并可以返回错误消息；如果验证通过，则返回 null。

或者，您可以利用 Laravel 验证器 的强大功能。为此，请向 validate 参数提供一个包含属性名称和所需验证规则的数组：

$copies = number(
    label: '您需要多少份副本？',
    validate: ['copies' => 'required|integer|min:1|max:100']
);

密码

password 函数类似于 text 函数，但用户的输入在控制台中输入时将被掩盖。这在询问密码等敏感信息时很有用：

use function Laravel\Prompts\password;

$password = password('你的密码是什么？');

您还可以包括占位符文本和信息提示：

$password = password(
    label: '你的密码是什么？',
    placeholder: '密码',
    hint: '至少 8 个字符。'
);

必填值

如果您需要输入值，可以传递 required 参数：

$password = password(
    label: '你的密码是什么？',
    required: true
);

如果您想自定义验证消息，也可以传递一个字符串：

$password = password(
    label: '你的密码是什么？',
    required: '密码是必填项。'
);

额外验证

最后，如果您想执行额外的验证逻辑，可以将闭包传递给 validate 参数：

$password = password(
    label: '你的密码是什么？',
    validate: fn (string $value) => match (true) {
        strlen($value) < 8 => '密码必须至少有 8 个字符。',
        default => null
    }
);

闭包将接收已输入的值，并可以返回错误消息，或者如果验证通过则返回 null。

或者，您可以利用 Laravel 的 validator。为此，请提供一个包含属性名称和所需验证规则的数组给 validate 参数：

$password = password(
    label: '你的密码是什么？',
    validate: ['password' => 'min:8']
);

确认

如果您需要询问用户“是或否”确认，可以使用 confirm 函数。用户可以使用箭头键或按 y 或 n 选择他们的响应。此函数将返回 true 或 false。

use function Laravel\Prompts\confirm;

$confirmed = confirm('您接受条款吗？');

您还可以包括默认值、自定义“是”和“否”标签的措辞以及信息提示：

$confirmed = confirm(
    label: '您接受条款吗？',
    default: false,
    yes: '我接受',
    no: '我拒绝',
    hint: '必须接受条款才能继续。'
);

要求“是”

如果需要，您可以通过传递 required 参数来要求用户选择“是”：

$confirmed = confirm(
    label: '您接受条款吗？',
    required: true
);

如果您想自定义验证消息，也可以传递一个字符串：

$confirmed = confirm(
    label: '您接受条款吗？',
    required: '您必须接受条款才能继续。'
);

选择

如果您需要用户从预定义的选项集中进行选择，可以使用 select 函数：

use function Laravel\Prompts\select;

$role = select(
    label: '用户应该具有什么角色？',
    options: ['成员', '贡献者', '所有者']
);

您还可以指定默认选择和信息提示：

$role = select(
    label: '用户应该具有什么角色？',
    options: ['成员', '贡献者', '所有者'],
    default: '所有者',
    hint: '角色可以随时更改。'
);

您还可以将关联数组传递给 options 参数，以便返回所选键而不是其值：

$role = select(
    label: '用户应该具有什么角色？',
    options: [
        'member' => '成员',
        'contributor' => '贡献者',
        'owner' => '所有者',
    ],
    default: 'owner'
);

最多显示五个选项，然后列表开始滚动。您可以通过传递 scroll 参数自定义此设置：

$role = select(
    label: '您想分配哪个类别？',
    options: Category::pluck('name', 'id'),
    scroll: 10
);

次要信息

info 参数可用于显示关于当前高亮选项的附加信息。当提供一个闭包时，它将接收当前高亮选项的值，并应返回一个字符串或 null：

$role = select(
    label: '用户应该拥有什么角色？',
    options: [
        'member' => '成员',
        'contributor' => '贡献者',
        'owner' => '所有者',
    ],
    info: fn (string $value) => match ($value) {
        'member' => '可以查看和评论。',
        'contributor' => '可以查看、评论和编辑。',
        'owner' => '对所有资源的完全访问权限。',
        default => null,
    }
);

如果信息不依赖于高亮选项，你也可以向 info 参数传递一个静态字符串：

$role = select(
    label: '用户应该拥有什么角色？',
    options: ['成员', '贡献者', '所有者'],
    info: '角色可以随时更改。'
);

额外验证

与其他提示函数不同，select 函数不接受 required 参数，因为不可能选择无选项。但是，如果您需要显示一个选项但阻止其被选择，可以将闭包传递给 validate 参数：

$role = select(
    label: '用户应该具有什么角色？',
    options: [
        'member' => '成员',
        'contributor' => '贡献者',
        'owner' => '所有者',
    ],
    validate: fn (string $value) =>
        $value === 'owner' && User::where('role', 'owner')->exists()
            ? '已经存在一个所有者。'
            : null
);

如果 options 参数是关联数组，则闭包将接收所选键，否则将接收所选值。闭包可以返回错误消息，或者如果验证通过则返回 null。

多选

如果您需要用户能够选择多个选项，可以使用 multiselect 函数：

use function Laravel\Prompts\multiselect;

$permissions = multiselect(
    label: '应该分配哪些权限？',
    options: ['读取', '创建', '更新', '删除']
);

您还可以指定默认选择和信息提示：

use function Laravel\Prompts\multiselect;

$permissions = multiselect(
    label: '应该分配哪些权限？',
    options: ['读取', '创建', '更新', '删除'],
    default: ['读取', '创建'],
    hint: '权限可以随时更新。'
);

您还可以将关联数组传递给 options 参数，以便返回所选选项的键而不是其值：

$permissions = multiselect(
    label: '应该分配哪些权限？',
    options: [
        'read' => '读取',
        'create' => '创建',
        'update' => '更新',
        'delete' => '删除',
    ],
    default: ['read', 'create']
);

最多显示五个选项，然后列表开始滚动。您可以通过传递 scroll 参数自定义此设置：

$categories = multiselect(
    label: '应该分配哪些类别？',
    options: Category::pluck('name', 'id'),
    scroll: 10
);

次要信息

info 参数可用于显示关于当前高亮选项的附加信息。当提供一个闭包时，它将接收当前高亮选项的值，并应返回一个字符串或 null：

$permissions = multiselect(
    label: '应该分配哪些权限？',
    options: [
        'read' => '读取',
        'create' => '创建',
        'update' => '更新',
        'delete' => '删除',
    ],
    info: fn (string $value) => match ($value) {
        'read' => '查看资源及其属性。',
        'create' => '创建新资源。',
        'update' => '修改现有资源。',
        'delete' => '永久删除资源。',
        default => null,
    }
);

要求值

默认情况下，用户可以选择零个或多个选项。您可以传递 required 参数来强制选择一个或多个选项：

$categories = multiselect(
    label: '应该分配哪些类别？',
    options: Category::pluck('name', 'id'),
    required: true
);

如果您想自定义验证消息，可以为 required 参数提供一个字符串：

$categories = multiselect(
    label: '应该分配哪些类别？',
    options: Category::pluck('name', 'id'),
    required: '您必须选择至少一个类别'
);

额外验证

如果您需要显示一个选项但阻止其被选择，可以将闭包传递给 validate 参数：

$permissions = multiselect(
    label: '用户应该具有什么权限？',
    options: [
        'read' => '读取',
        'create' => '创建',
        'update' => '更新',
        'delete' => '删除',
    ],
    validate: fn (array $values) => ! in_array('read', $values)
        ? '所有用户都需要读取权限。'
        : null
);

如果 options 参数是关联数组，则闭包将接收所选键，否则将接收所选值。闭包可以返回错误消息，或者如果验证通过则返回 null。

建议

suggest 函数可用于为可能的选择提供自动完成。用户仍然可以提供任何答案，无论自动完成提示如何：

use function Laravel\Prompts\suggest;

$name = suggest('你叫什么名字？', ['Taylor', 'Dayle']);

或者，您可以将闭包作为第二个参数传递给 suggest 函数。每次用户输入一个字符时，都会调用闭包。闭包应接受一个包含用户输入的字符串参数，并返回一个用于自动完成的选项数组：

$name = suggest(
    label: '你叫什么名字？',
    options: fn ($value) => collect(['Taylor', 'Dayle'])
        ->filter(fn ($name) => Str::contains($name, $value, ignoreCase: true))
)

您还可以包括占位符文本、默认值和信息提示：

$name = suggest(
    label: '你叫什么名字？',
    options: ['Taylor', 'Dayle'],
    placeholder: '例如 Taylor',
    default: $user?->name,
    hint: '这将显示在您的个人资料上。'
);

次要信息

info 参数可用于显示关于当前高亮选项的附加信息。当提供一个闭包时，它将接收当前高亮选项的值，并应返回一个字符串或 null：

$name = suggest(
    label: '你叫什么名字？',
    options: ['Taylor', 'Dayle'],
    info: fn (string $value) => match ($value) {
        'Taylor' => '管理员',
        'Dayle' => '贡献者',
        default => null,
    }
);

必填值

如果您需要输入值，可以传递 required 参数：

$name = suggest(
    label: '你叫什么名字？',
    options: ['Taylor', 'Dayle'],
    required: true
);

如果您想自定义验证消息，也可以传递一个字符串：

$name = suggest(
    label: '你叫什么名字？',
    options: ['Taylor', 'Dayle'],
    required: '您的名字是必填项。'
);

额外验证

最后，如果您想执行额外的验证逻辑，可以将闭包传递给 validate 参数：

$name = suggest(
    label: '你叫什么名字？',
    options: ['Taylor', 'Dayle'],
    validate: fn (string $value) => match (true) {
        strlen($value) < 3 => '名字必须至少有 3 个字符。',
        strlen($value) > 255 => '名字不能超过 255 个字符。',
        default => null
    }
);

闭包将接收已输入的值，并可以返回错误消息，或者如果验证通过则返回 null。

或者，您可以利用 Laravel 的 validator。为此，请提供一个包含属性名称和所需验证规则的数组给 validate 参数：

$name = suggest(
    label: '你叫什么名字？',
    options: ['Taylor', 'Dayle'],
    validate: ['name' => 'required|min:3|max:255']
);

搜索

如果您有很多选项供用户选择，search 函数允许用户输入搜索查询以在使用箭头键选择选项之前过滤结果：

use function Laravel\Prompts\search;

$id = search(
    label: '搜索应接收邮件的用户',
    options: fn (string $value) => strlen($value) > 0
        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
        : []
);

闭包将接收用户输入的文本，并且必须返回一个选项数组。如果您返回一个关联数组，则返回所选选项的键，否则返回其值。

在过滤一个您打算返回值的数组时，您应该使用 array_values 函数或 values 集合方法，以确保数组不会变成关联数组：

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

$selected = search(
    label: '搜索应接收邮件的用户',
    options: fn (string $value) => $names
        ->filter(fn ($name) => Str::contains($name, $value, ignoreCase: true))
        ->values()
        ->all(),
);

您还可以包括占位符文本和信息提示：

$id = search(
    label: '搜索应接收邮件的用户',
    placeholder: '例如 Taylor Otwell',
    options: fn (string $value) => strlen($value) > 0
        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    hint: '用户将立即收到电子邮件。'
);

最多显示五个选项，然后列表开始滚动。您可以通过传递 scroll 参数自定义此设置：

$id = search(
    label: '搜索应接收邮件的用户',
    options: fn (string $value) => strlen($value) > 0
        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    scroll: 10
);

次要信息

info 参数可用于显示关于当前高亮选项的附加信息。当提供一个闭包时，它将接收当前高亮选项的值，并应返回一个字符串或 null：

$id = search(
    label: '搜索应接收邮件的用户',
    options: fn (string $value) => strlen($value) > 0
        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    info: fn (int $userId) => User::find($userId)?->email
);

额外验证

如果您想执行额外的验证逻辑，可以将闭包传递给 validate 参数：

$id = search(
    label: '搜索应接收邮件的用户',
    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 '该用户已选择不接收邮件。';
        }
    }
);

如果 options 闭包返回一个关联数组，则闭包将接收所选键，否则将接收所选值。闭包可以返回错误消息，或者如果验证通过则返回 null。

多重搜索

如果您有很多可搜索的选项，并且需要用户能够选择多个项目，multisearch 函数允许用户输入搜索查询以在使用箭头键和空格键选择选项之前过滤结果：

use function Laravel\Prompts\multisearch;

$ids = multisearch(
    '搜索应接收邮件的用户',
    fn (string $value) => strlen($value) > 0
        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
        : []
);

闭包将接收用户输入的文本，并且必须返回一个选项数组。如果您返回一个关联数组，则返回所选选项的键，否则返回其值。

在过滤一个您打算返回值的数组时，您应该使用 array_values 函数或 values 集合方法，以确保数组不会变成关联数组：

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

$selected = multisearch(
    label: '搜索应接收邮件的用户',
    options: fn (string $value) => $names
        ->filter(fn ($name) => Str::contains($name, $value, ignoreCase: true))
        ->values()
        ->all(),
);

您还可以包括占位符文本和信息提示：

$ids = multisearch(
    label: '搜索应接收邮件的用户',
    placeholder: '例如 Taylor Otwell',
    options: fn (string $value) => strlen($value) > 0
        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    hint: '用户将立即收到电子邮件。'
);

最多显示五个选项，然后列表开始滚动。您可以通过提供 scroll 参数自定义此设置：

$ids = multisearch(
    label: '搜索应接收邮件的用户',
    options: fn (string $value) => strlen($value) > 0
        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    scroll: 10
);

次要信息

info 参数可用于显示关于当前高亮选项的附加信息。当提供一个闭包时，它将接收当前高亮选项的值，并应返回一个字符串或 null：

$ids = multisearch(
    label: '搜索应接收邮件的用户',
    options: fn (string $value) => strlen($value) > 0
        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    info: fn (int $userId) => User::find($userId)?->email
);

要求值

默认情况下，用户可以选择零个或多个选项。您可以传递 required 参数来强制选择一个或多个选项：

$ids = multisearch(
    label: '搜索应接收邮件的用户',
    options: fn (string $value) => strlen($value) > 0
        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    required: true
);

如果您想自定义验证消息，也可以为 required 参数提供一个字符串：

$ids = multisearch(
    label: '搜索应接收邮件的用户',
    options: fn (string $value) => strlen($value) > 0
        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    required: '您必须选择至少一个用户。'
);

额外验证

如果您想执行额外的验证逻辑，可以将闭包传递给 validate 参数：

$ids = multisearch(
    label: '搜索应接收邮件的用户',
    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(', ', ', 和 ').' 已选择不接收。';
        }
    }
);

如果 options 闭包返回一个关联数组，则闭包将接收所选键，否则将接收所选值。闭包可以返回错误消息，或者如果验证通过则返回 null。

暂停

pause 函数可用于向用户显示信息文本，并等待他们按下 Enter / Return 键确认继续：

use function Laravel\Prompts\pause;

pause('按 ENTER 键继续。');

自动补全

autocomplete 函数可用于为可能的选项提供内联的自动补全功能。当用户输入时，匹配其输入的建议将作为虚影文本出现，可以通过按下 Tab 键或右箭头键来接受：

use function Laravel\Prompts\autocomplete;

$name = autocomplete(
    label: '你叫什么名字？',
    options: ['Taylor', 'Dayle', 'Jess', 'Nuno', 'Tim']
);

你还可以包含占位符文本、默认值和信息提示：

$name = autocomplete(
    label: '你叫什么名字？',
    options: ['Taylor', 'Dayle', 'Jess', 'Nuno', 'Tim'],
    placeholder: '例如：Taylor',
    default: $user?->name,
    hint: '使用 Tab 键接受，上下键循环。'
);

动态选项

你也可以传递一个闭包来根据用户的输入动态生成选项。该闭包会在用户每次键入字符时被调用，并应返回一个用于自动补全的选项数组：

$file = autocomplete(
    label: '哪个文件？',
    options: fn (string $value) => collect($files)
        ->filter(fn ($file) => str_starts_with(strtolower($file), strtolower($value)))
        ->values()
        ->all(),
);

必需值

如果需要强制输入值，可以传递 required 参数：

$name = autocomplete(
    label: '你叫什么名字？',
    options: ['Taylor', 'Dayle', 'Jess', 'Nuno', 'Tim'],
    required: true
);

如果你想自定义验证消息，也可以传递一个字符串：

$name = autocomplete(
    label: '你叫什么名字？',
    options: ['Taylor', 'Dayle', 'Jess', 'Nuno', 'Tim'],
    required: '你的名字是必填项。'
);

附加验证

最后，如果你想执行额外的验证逻辑，可以向 validate 参数传递一个闭包：

$name = autocomplete(
    label: '你叫什么名字？',
    options: ['Taylor', 'Dayle', 'Jess', 'Nuno', 'Tim'],
    validate: fn (string $value) => match (true) {
        strlen($value) < 3 => '名字必须至少包含 3 个字符。',
        strlen($value) > 255 => '名字不能超过 255 个字符。',
        default => null
    }
);

该闭包将接收已输入的值，并可能返回一条错误消息；如果验证通过，则返回 null。

在验证前转换输入

有时您可能希望在验证发生之前转换提示输入。例如，您可能希望删除任何提供的字符串中的空白。为此，许多提示函数提供了一个 transform 参数，该参数接受一个闭包：

$name = text(
    label: '你叫什么名字？',
    transform: fn (string $value) => trim($value),
    validate: fn (string $value) => match (true) {
        strlen($value) < 3 => '名字必须至少有 3 个字符。',
        strlen($value) > 255 => '名字不能超过 255 个字符。',
        default => null
    }
);

表单

通常，您将有多个提示将按顺序显示以收集信息，然后再执行其他操作。您可以使用 form 函数为用户创建一组分组的提示：

use function Laravel\Prompts\form;

$responses = form()
    ->text('你叫什么名字？', required: true)
    ->password('你的密码是什么？', validate: ['password' => 'min:8'])
    ->confirm('您接受条款吗？')
    ->submit();

submit 方法将返回一个包含表单提示的所有响应的数字索引数组。但是，您可以通过 name 参数为每个提示提供一个名称。当提供名称时，可以通过该名称访问命名提示的响应：

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

$responses = form()
    ->text('你叫什么名字？', required: true, name: 'name')
    ->password(
        label: '你的密码是什么？',
        validate: ['password' => 'min:8'],
        name: 'password'
    )
    ->confirm('您接受条款吗？')
    ->submit();

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

使用 form 函数的主要好处是用户可以使用 CTRL + U 返回表单中的上一个提示。这允许用户在不需要取消和重新启动整个表单的情况下修复错误或更改选择。

如果您需要对表单中的提示进行更细粒度的控制，可以调用 add 方法而不是直接调用提示函数。add 方法会传递用户提供的所有先前响应：

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

$responses = form()
    ->text('你叫什么名字？', required: true, name: 'name')
    ->add(function ($responses) {
        return text("你多大了，{$responses['name']}？");
    }, name: 'age')
    ->submit();

outro("你的名字是 {$responses['name']}，你今年 {$responses['age']} 岁。");

信息消息

note、info、warning、error 和 alert 函数可用于显示信息消息：

use function Laravel\Prompts\info;

info('包安装成功。');

表格

table 函数使显示多行和多列数据变得容易。您只需提供列名和表格数据：

use function Laravel\Prompts\table;

table(
    headers: ['姓名', '电子邮件'],
    rows: User::all(['name', 'email'])->toArray()
);

旋转

spin 函数在执行指定的回调时显示一个旋转器以及可选的消息。它用于指示正在进行的过程，并在完成后返回回调的结果：

use function Laravel\Prompts\spin;

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

警告

spin 函数需要 PCNTL PHP 扩展来为微调器添加动画效果。当此扩展不可用时，将显示微调器的静态版本。

进度条

对于长时间运行的任务，显示进度条可以帮助用户了解任务的完成情况。使用 progress 函数，Laravel 将显示一个进度条，并在每次迭代给定的可迭代值时推进其进度：

use function Laravel\Prompts\progress;

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

progress 函数的行为类似于 map 函数，并将返回一个包含回调每次迭代返回值的数组。

回调还可以接受 Laravel\Prompts\Progress 实例，允许您在每次迭代时修改标签和提示：

$users = progress(
    label: '更新用户',
    steps: User::all(),
    callback: function ($user, $progress) {
        $progress
            ->label("更新 {$user->name}")
            ->hint("创建于 {$user->created_at}");

        return $this->performTask($user);
    },
    hint: '这可能需要一些时间。'
);

有时，您可能需要更手动地控制进度条的推进。首先，定义过程将迭代的步骤总数。然后，在处理每个项目后，通过 advance 方法推进进度条：

$progress = progress(label: '更新用户', steps: 10);

$users = User::all();

$progress->start();

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

    $progress->advance();
}

$progress->finish();

任务

task 函数在执行给定的回调时，会显示一个带有旋转指示器和滚动实时输出区域的带标签任务。它非常适合用于封装耗时较长的流程，例如依赖安装或部署脚本，可以提供正在发生情况的实时可见性：

use function Laravel\Prompts\task;

task(
    label: '正在安装依赖',
    callback: function ($logger) {
        // 耗时流程...
    }
);

回调函数接收一个 Logger 实例，您可以使用它在任务的输出区域中显示日志行、状态消息和流式文本。

警告

task 函数需要 PCNTL PHP 扩展来实现旋转指示器的动画效果。如果此扩展不可用，则会显示一个静态版本的任务。

记录日志行

line 方法向任务的滚动输出区域写入单条日志行：

task(
    label: '正在安装依赖',
    callback: function ($logger) {
        $logger->line('正在解析包...');
        // ...
        $logger->line('正在下载 laravel/framework');
        // ...
    }
);

状态消息

您可以使用 success、warning 和 error 方法来显示状态消息。这些消息会作为稳定的、高亮显示的信息出现在滚动日志区域的上方：

task(
    label: '正在部署应用',
    callback: function ($logger) {
        $logger->line('正在拉取最新更改...');
        // ...
        $logger->success('更改已拉取！');

        $logger->line('正在运行迁移...');
        // ...
        $logger->warning('没有需要运行的新迁移。');

        $logger->line('正在清除缓存...');
        // ...
        $logger->success('缓存已清除！');
    }
);

更新标签

label 方法允许您在任务运行时更新其标签：

task(
    label: '正在启动部署...',
    callback: function ($logger) {
        $logger->label('正在拉取最新更改...');
        // ...
        $logger->label('正在运行迁移...');
        // ...
        $logger->label('正在清除缓存...');
        // ...
    }
);

流式文本

对于像 AI 生成的响应这样逐字逐块增量产生输出的过程，可以使用 partial 方法来逐字或逐块地流式输出文本。流式输出完成后，调用 commitPartial 来最终确定输出：

task(
    label: '正在生成响应...',
    callback: function ($logger) {
        foreach ($words as $word) {
            $logger->partial($word . ' ');
        }

        $logger->commitPartial();
    }
);

自定义输出限制

默认情况下，任务最多显示 10 行滚动输出。您可以通过 limit 参数自定义此数值：

task(
    label: '正在安装依赖',
    callback: function ($logger) {
        // ...
    },
    limit: 20
);

流

stream 函数将文本以流式方式显示到终端中，非常适合用于显示 AI 生成的内容或任何逐步到达的文本：

use function Laravel\Prompts\stream;

$stream = stream();

foreach ($words as $word) {
    $stream->append($word . ' ');
    usleep(25_000); // 模拟块之间的延迟...
}

$stream->close();

append 方法向流中添加文本，并以渐显效果呈现。当所有内容都流式输出完毕后，调用 close 方法以最终确定输出并恢复光标。

终端标题

title 函数用于更新用户终端窗口或标签页的标题：

use function Laravel\Prompts\title;

title('正在安装依赖');

要将终端标题重置为默认值，请传递一个空字符串：

title('');

通知

notify 函数从终端发送本地桌面通知：

use function Laravel\Prompts\notify;

notify('构建完成', '已部署到生产环境');

macOS（通过 osascript）和 Linux（通过 notify-send，备选 kdialog）均支持通知功能。

在 macOS 上，您还可以包含 subtitle（副标题）和 sound（声音）：

notify(
    title: '构建完成',
    body: '已部署到生产环境',
    subtitle: 'staging-server',
    sound: 'Glass',
);

在 Linux 上，您可以提供自定义的 icon（图标）：

notify(
    title: '构建完成',
    body: '已部署到生产环境',
    icon: '/path/to/icon.png',
);

清除终端

clear 函数可用于清除用户的终端：

use function Laravel\Prompts\clear;

clear();

终端注意事项

终端宽度

如果任何标签、选项或验证消息的长度超过用户终端中的“列”数，它将自动截断以适应。如果您的用户可能使用较窄的终端，请考虑最小化这些字符串的长度。通常安全的最大长度是 74 个字符，以支持 80 个字符的终端。

终端高度

对于任何接受 scroll 参数的提示，配置的值将自动减少以适应用户终端的高度，包括验证消息的空间。

不支持的环境和回退

Laravel 提示支持 macOS、Linux 和 Windows 的 WSL。由于 Windows 版本的 PHP 存在限制，目前无法在 WSL 之外的 Windows 上使用 Laravel 提示。

因此，Laravel 提示支持回退到其他实现，例如 Symfony Console Question Helper。

注意

在 Laravel 框架中使用 Laravel 提示时，已为您配置了每个提示的回退，并将在不支持的环境中自动启用。

回退条件

如果您不使用 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 : '必填。'
                );
            }

            if ($prompt->validate) {
                $error = ($prompt->validate)($answer ?? '');

                if ($error) {
                    throw new \RuntimeException($error);
                }
            }

            return $answer;
        });

    return (new SymfonyStyle($input, $output))
        ->askQuestion($question);
});

必须为每个提示类单独配置回退。闭包将接收提示类的实例，并且必须返回提示的适当类型。

Testing

Laravel 提供了多种方法来测试你的命令是否显示预期的 Prompt 消息：

Pest

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', 'taylor@example.com'],
                ['Jason Beggs', 'jason@example.com'],
            ]
        )
        ->assertExitCode(0);
});

PHPUnit

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', 'taylor@example.com'],
                ['Jason Beggs', 'jason@example.com'],
            ]
        )
        ->assertExitCode(0);
}