Интерактивные Подсказки в Laravel 10.x: Создание и Работа

Введение
Установка
Доступные запросы
Информационные сообщения
Таблицы
Вращение
Панель прогресса
Рассмотрение терминала
Неподдерживаемые среды и запасные варианты

Введение

Laravel Prompts - это PHP-пакет для добавления красивых и удобных форм в ваши командные приложения с интерфейсом командной строки, с функционалом, напоминающим браузер, включая текстовые подсказки и валидацию.

Laravel Prompts идеально подходит для получения ввода пользователя в ваших командах Artisan, но его также можно использовать в любом PHP-проекте с командной строки.

Примечание Laravel Prompts поддерживает macOS, Linux и Windows с WSL. Дополнительные сведения можно найти в нашей документации по неподдерживаемым средам и запасным вариантам.

Установка

Laravel Prompts уже включен в последний релиз Laravel.

Laravel Prompts также можно установить в ваши другие проекты на PHP, используя менеджер пакетов Composer:

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

Подтверждение

Если вам нужно запросить у пользователя подтверждение "да" или "нет", вы можете использовать функцию 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.'
);

Требуется "Да"

При необходимости вы можете потребовать от пользователей выбор "Да", передав аргумент 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:

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

До пяти вариантов отобразятся, прежде чем начнется прокрутка списка. Вы можете настроить это, передав аргумент 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(
    'Какие разрешения должны быть назначены?',
    ['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']
);

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

Требование значения

По умолчанию пользователь может выбрать ноль или более вариантов. Вы можете передать аргумент required, чтобы обязать выбрать один или более вариантов:

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

Валидация

Вы можете передать замыкание аргументу 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. Замыкание будет вызываться каждый раз, когда пользователь вводит символ. Замыкание должно принимать параметр - строку с вводом пользователя на данный момент, и возвращать массив вариантов для автозаполнения:

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

Дополнительная валидация

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

До пяти вариантов будет отображаться, прежде чем начнется прокрутка списка. Вы можете настроить это, передав аргумент 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, если валидация прошла успешно.

Множественный поиск

Если у вас есть много вариантов для выбора и вам нужно, чтобы пользователь мог выбрать несколько элементов, функция multisearch позволяет пользователю вводить поисковый запрос для фильтрации результатов перед выбором вариантов с помощью стрелок вниз и вверх и клавиши пробела:

use function Laravel\Prompts\multisearch;
 
$ids = multisearch(
    'Search for the users that should receive the mail',
    fn (string $value) => strlen($value) > 0
        ? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
        : []
);

Замыкание получит текст, который был введен пользователем на данный момент, и должно вернуть массив вариантов. Если вы возвращаете ассоциативный массив, то будут возвращены ключи выбранных вариантов, в противном случае будут возвращены их значения.

Вы также можете включить текст-заглушку и информационную подсказку:

$ids = multisearch(
    label: 'Search for the users 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.'
);

До пяти вариантов будет отображаться, прежде чем начнется прокрутка списка. Вы можете настроить это, предоставив аргумент scroll:

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

Требование значения

По умолчанию пользователь может выбрать ноль или более вариантов. Вы можете передать аргумент required, чтобы требовать один или несколько вариантов:

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

Если вы хотите настроить текст сообщения об ошибке, вы также можете передать строку в аргумент required:

$ids = multisearch(
    'Search for the users that should receive the mail',
    fn (string $value) => strlen($value) > 0
        ? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    required: 'You must select at least one user.'
);

Валидация

Если вы хотите выполнить дополнительную логику валидации, вы можете передать замыкание в аргумент validate:

$ids = multisearch(
    label: 'Search for the users that should receive the mail',
    options: fn (string $value) => strlen($value) > 0
        ? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    validate: function (array $values) {
        $optedOut = User::where('name', 'like', '%a%')->findMany($values);
 
        if ($optedOut->isNotEmpty()) {
            return $optedOut->pluck('name')->join(', ', ', and ').' have opted out.';
        }
    }
);

Если замыкание options возвращает ассоциативный массив, то замыкание получит выбранные ключи, в противном случае - выбранные значения. Замыкание может вернуть сообщение об ошибке или null, если валидация прошла успешно.

Информационные сообщения

Функции note, info, warning, error и alert могут использоваться для отображения информационных сообщений:

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

Внимание Функция spin требует расширения PHP pcntl для анимации спиннера. Когда это расширение недоступно, вместо него будет отображаться статическая версия спиннера.

Панели прогресса

Для длительных задач может быть полезно показать полосу прогресса, которая информирует пользователей о степени завершенности задачи. Используя функцию progress, Laravel отобразит полосу прогресса и продвинет ее для каждой итерации по указанному значению:

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

Функция progress действует как функция отображения (map function) и вернет массив, содержащий возвращаемое значение каждой итерации вашего обратного вызова.

Обратный вызов также может принимать экземпляр \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();

Рассмотрение терминала

Ширина терминала

Если длина любой метки, опции или сообщения об ошибке превышает количество "столбцов" в терминале пользователя, она будет автоматически усечена для соответствия. Рассмотрите возможность минимизации длины этих строк, если ваши пользователи могут использовать более узкие терминалы. Обычно безопасной максимальной длиной является 74 символа для поддержки терминала шириной 80 символов.

Высота терминала

Для любых подсказок, принимающих аргумент scroll, настроенное значение автоматически уменьшится до высоты терминала пользователя, включая место для сообщения о валидации.

Неподдерживаемые среды и запасные варианты

Laravel Prompts поддерживает macOS, Linux и Windows с WSL. Из-за ограничений в версии PHP для Windows в настоящее время невозможно использовать Laravel Prompts на Windows за пределами WSL.

По этой причине Laravel Prompts поддерживает откат к альтернативной реализации, такой как Symfony Console Question Helper.

Примечание При использовании Laravel Prompts с фреймворком Laravel для каждого запроса настроены запасные варианты и они будут автоматически включены в неподдерживаемых средах.

Условия запасного варианта

Если вы не используете Laravel или нужно настроить, когда следует использовать резервное поведение, вы можете передать булево значение методу fallbackWhen статического класса Prompt:

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

Откаты должны быть настроены индивидуально для каждого класса подсказки. Замыкание получит экземпляр класса подсказки и должно вернуть соответствующий тип для подсказки.

Prompts

Присоединяйся к нашему Telegram сообществу @webblend!

Введение

Установка

Доступные запросы

Текст

Обязательные значения

Дополнительная валидация

Пароль

Обязательные значения

Дополнительная валидация

Подтверждение

Требуется "Да"

Выбор

Валидация

Множественный выбор

Требование значения

Валидация

Подсказка

Обязательные значения

Дополнительная валидация

Поиск

Валидация

Множественный поиск

Требование значения

Валидация

Информационные сообщения

Таблицы

Вращение

Панели прогресса

Рассмотрение терминала

Ширина терминала

Высота терминала

Неподдерживаемые среды и запасные варианты

Условия запасного варианта

Поведение запасного варианта

📘 Раздел cтатей о Laravel: скоро