Laravel Prompts - Knowledge of Laravel

Inleiding

Laravel Prompts is een PHP-pakket voor het toevoegen van mooie, gebruiksvriendelijke interactieve formulieren aan commandline-applicaties. Het biedt een ervaring die dicht bij browserformulieren ligt, met placeholdertekst en validatie. Omdat je het rechtstreeks in de code van je Artisan-commando’s kunt aanroepen, schrijf je vragen aan de gebruiker eenvoudig en intuïtief.

Laravel Prompts ondersteunt macOS, Linux en Windows (WSL). In niet-ondersteunde omgevingen wordt automatisch overgeschakeld naar fallbackgedrag.

Installatie

Laravel Prompts wordt met Laravel zelf meegeleverd; extra installatie is niet nodig. Wil je het in een ander PHP-project gebruiken, dan installeer je het met Composer.

composer require laravel/prompts

Basale promptfuncties

text — tekstinvoer

Met text() vraag je de gebruiker om een string in te voeren.

use function Laravel\Prompts\text;

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

Je kunt een placeholder, standaardwaarde en hint instellen.

$name = text(
    label: 'What is your name?',
    placeholder: 'E.g. Taylor Otwell',
    default: $user?->name,
    hint: 'This will be displayed on your profile.'
);

Met required maak je de invoer verplicht. Ook het validatiebericht is aanpasbaar.

$name = text(
    label: 'What is your name?',
    required: 'Your name is required.'
);

Met een validate-closure voer je extra validatie uit. De closure geeft een foutmelding terug, of null bij succes.

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

Je kunt ook Laravel-validatieregels als array opgeven.

$name = text(
    label: 'What is your name?',
    validate: ['name' => 'required|max:255|unique:users']
);

textarea — meerregelige tekstinvoer

Met textarea() accepteer je invoer over meerdere regels.

use function Laravel\Prompts\textarea;

$story = textarea('Tell me a story.');

number — numerieke invoer

Met number() accepteer je een getal. Met de pijltjestoetsen omhoog/omlaag kun je de waarde verhogen of verlagen.

use function Laravel\Prompts\number;

$copies = number(
    label: 'How many copies would you like?',
    default: 1,
    validate: ['copies' => 'required|integer|min:1|max:100']
);

password — wachtwoordinvoer

password() werkt zoals tekstinvoer, maar de ingevoerde tekst wordt niet op het scherm getoond.

use function Laravel\Prompts\password;

$password = password('What is your password?');

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

confirm — ja/nee-bevestiging

Met confirm() vraag je de gebruiker om een keuze uit twee opties. Het geeft true of false terug.

use function Laravel\Prompts\confirm;

$confirmed = confirm('Do you accept the terms?');

Je kunt de standaardwaarde en de labeltekst aanpassen.

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

select — keuzelijst

Met select() laat je de gebruiker één optie uit een lijst kiezen.

use function Laravel\Prompts\select;

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

Gebruik je een associatieve array, dan wordt de sleutel — niet het weergavelabel — de returnwaarde.

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

Met scroll wijzig je hoeveel opties er zichtbaar zijn voordat er gescrold wordt (standaard 5).

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

multiselect — meervoudige selectie

Met multiselect() laat je meerdere opties tegelijk kiezen.

use function Laravel\Prompts\multiselect;

$permissions = multiselect(
    label: 'What permissions should be assigned?',
    options: ['Read', 'Create', 'Update', 'Delete']
);

Met required maak je het kiezen van minstens één optie verplicht.

$permissions = multiselect(
    label: 'What permissions should be assigned?',
    options: ['Read', 'Create', 'Update', 'Delete'],
    required: 'At least one permission must be selected.'
);

suggest — invoer met autocomplete

suggest() toont suggesties maar accepteert ook vrije invoer.

use function Laravel\Prompts\suggest;

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

Geef je een closure door, dan kun je de suggesties dynamisch filteren op basis van de invoer.

$name = suggest(
    label: 'What is your name?',
    options: fn (string $value) => collect(['Taylor', 'Tobi', 'Dries'])
        ->filter(fn ($name) => str_starts_with($name, $value))
        ->values()
        ->all()
);

search — dynamisch zoeken

search() werkt de lijst met suggesties bij bij elke toetsaanslag. De array die de closure teruggeeft vormt de suggesties.

use function Laravel\Prompts\search;

$userId = search(
    label: 'Search for the user that should receive the mail',
    options: fn (string $value) => strlen($value) > 0
        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
        : []
);

multisearch — dynamisch zoeken met meervoudige selectie

Met multisearch() kun je via dynamisch zoeken meerdere opties selecteren.

use function Laravel\Prompts\multisearch;

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

pause — pauzeren

Met pause() pauzeer je de verwerking totdat de gebruiker op Enter drukt.

use function Laravel\Prompts\pause;

pause('Press ENTER to continue.');

autocomplete — inline aanvullen

autocomplete() is een functie voor inline aanvullen die suggesties als ghost text toont. Anders dan bij suggest() verschijnt bij elke toetsaanslag de best passende suggestie als ghost text, en met de Tab-toets of de pijl naar rechts bevestig je de aanvulling.

use function Laravel\Prompts\autocomplete;

$name = autocomplete(
    label: 'What is your name?',
    options: ['Taylor', 'Dayle', 'Jess', 'Nuno', 'Tim']
);

Je kunt een placeholder, standaardwaarde en hint instellen.

$name = autocomplete(
    label: 'What is your name?',
    options: ['Taylor', 'Dayle', 'Jess', 'Nuno', 'Tim'],
    placeholder: 'E.g. Taylor',
    default: $user?->name,
    hint: 'Use Tab to accept, up/down to cycle.'
);

Geef je een closure door, dan genereer je de suggesties dynamisch op basis van de invoer.

$file = autocomplete(
    label: 'Which file?',
    options: fn (string $value) => collect($files)
        ->filter(fn ($file) => str_starts_with(strtolower($file), strtolower($value)))
        ->values()
        ->all(),
);

Validatie

Alle promptfuncties ondersteunen validatie via het validate-argument.

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

Geeft de closure een string terug, dan wordt die als foutmelding getoond en wordt om nieuwe invoer gevraagd. Geeft hij null terug, dan is de validatie geslaagd. Je kunt ook Laravel-validatieregels in arrayvorm gebruiken.

$name = text(
    label: 'What is your name?',
    validate: ['name' => 'required|max:255|unique:users']
);

Gebruik het transform-argument om de invoer vóór de validatie te transformeren.

$name = text(
    label: 'What is your name?',
    transform: fn (string $value) => trim($value),
    validate: fn (string $value) => match (true) {
        strlen($value) === 0 => 'The name must not be empty.',
        default => null
    }
);

Formulieren

Met form() bundel je meerdere prompts en kun je vóór voltooiing in één keer annuleren.

use function Laravel\Prompts\form;

$responses = form()
    ->text('What is your name?', required: true, name: 'name')
    ->password('What is your password?', validate: ['password' => 'min:8'], name: 'password')
    ->confirm('Do you accept the terms?')
    ->submit();

$name     = $responses['name'];
$password = $responses['password'];
$confirmed = $responses[2];

Informatie-uitvoer

Er zijn functies om tekstberichten met opmaak uit te voeren.

use function Laravel\Prompts\info;
use function Laravel\Prompts\warning;
use function Laravel\Prompts\error;
use function Laravel\Prompts\alert;
use function Laravel\Prompts\note;

note('Prepare for launch.');
info('User created successfully.');
warning('This action cannot be undone.');
error('Something went wrong.');
alert('Critical failure detected!');

Callouts

callout() toont een label en inhoud omkaderd. Ideaal om belangrijke informatie te laten opvallen, zoals deploysamenvattingen, foutdetails en statusupdates.

use function Laravel\Prompts\callout;

callout(
    label: 'Environment Configured',
    content: 'Your application is running in production mode with 4 workers.',
);

Geef je bij het type-argument 'warning' of 'error' op, dan verandert de visuele stijl.

callout(
    label: 'Deprecation Notice',
    content: 'The `--prefer-stable` flag will be removed in v4.0.',
    type: 'warning',
);

callout(
    label: 'Database Connection Failed',
    content: 'Could not connect to MySQL on 127.0.0.1:3306.',
    type: 'error',
);

Met het info-argument voeg je een voettekstregel toe. Handig om metadata zoals ID’s en timestamps te tonen.

callout(
    label: 'Deployment Summary',
    content: 'Your application was deployed to production.',
    info: 'deploy-id: d4f8a2c',
);

Rijke inhoud

Geef je in plaats van een string een array door, dan maak je een gestructureerde, rijke callout. De Element-klasse heeft factorymethodes voor koppen, opsommingslijsten, genummerde lijsten, sleutel-waardelijsten en links.

use Laravel\Prompts\Elements\Element;
use function Laravel\Prompts\callout;

callout('Deployment Summary', [
    'Your application was deployed to production at 2024-03-15 14:32 UTC.',
    Element::heading('What Changed'),
    Element::bulletedList([
        'Migrated 3 pending database migrations',
        'Cleared and rebuilt route cache',
        'Restarted 4 queue workers',
    ]),
    Element::heading('Next Steps'),
    Element::numberedList([
        'Verify the health check endpoint at /up',
        'Monitor error rates for the next 15 minutes',
        'Confirm background jobs are processing',
    ]),
]);

Met Element::keyValueList toon je gelabelde data.

callout('Database Connection Failed', [
    'Could not connect to the database server.',
    Element::keyValueList([
        'Host'     => '127.0.0.1',
        'Port'     => '3306',
        'Database' => 'forge',
        'Status'   => 'Connection refused',
    ]),
], type: 'error');

Element::link genereert klikbare hyperlinks in terminals die OSC 8 ondersteunen. Je kunt alleen een URL doorgeven, of een URL met een eigen label.

callout('Server Health Check', [
    'Multiple services are reporting degraded performance.',
    Element::heading('Affected Services'),
    'Look here: '.Element::link('https://example.com/health', 'Health Dashboard'),
    Element::link('https://example.com/health'),
]);

Laat je het label weg, dan wordt de URL als linktekst getoond.

Tabellen tonen

Met table() toon je data in tabelvorm.

use function Laravel\Prompts\table;

table(
    headers: ['Name', 'Email'],
    rows: User::all(['name', 'email'])->toArray()
);

Spin (laadindicator)

spin() toont een laadindicator terwijl de closure wordt uitgevoerd.

use function Laravel\Prompts\spin;

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

Voor spin() is de PHP-extensie pcntl vereist. In omgevingen waar die niet beschikbaar is, wordt de spinner niet getoond.

Voortgangsbalken

Met progress() toon je visueel de voortgang van een herhaalde bewerking.

use function Laravel\Prompts\progress;

$users = progress(
    label: 'Updating users',
    steps: User::all(),
    callback: fn ($user) => $this->performTask($user),
    hint: 'This may take some time.'
);

Je kunt de voortgangsbalk ook handmatig aansturen.

$progress = progress(label: 'Uploading files', steps: count($files));

$progress->start();

foreach ($files as $file) {
    $this->uploadFile($file);
    $progress->advance();
}

$progress->finish();

Taken

task() toont tijdens het uitvoeren van de callback een spinner en een scrolbaar live-uitvoergebied. Ideaal om langlopende processen te wrappen, zoals het installeren van dependencies of deployscripts, zodat je in realtime ziet wat er gebeurt.

use function Laravel\Prompts\task;

task(
    label: 'Installing dependencies',
    callback: function ($logger) {
        // Langlopende verwerking...
    }
);

De callback ontvangt een Logger-instantie waarmee je logregels en statusberichten in realtime kunt tonen.

Voor task() is de PHP-extensie pcntl vereist. In omgevingen waar die niet beschikbaar is, wordt teruggevallen op statische weergave.

Logregels uitvoeren

Met de line-methode schrijf je regel voor regel logs naar het scrollende uitvoergebied.

task(
    label: 'Installing dependencies',
    callback: function ($logger) {
        $logger->line('Resolving packages...');
        $logger->line('Downloading laravel/framework');
    }
);

Statusberichten

Met success, warning en error toon je gemarkeerde berichten die vast bovenaan het scrollende loggebied staan.

task(
    label: 'Deploying application',
    callback: function ($logger) {
        $logger->line('Pulling latest changes...');
        $logger->success('Changes pulled!');

        $logger->line('Running migrations...');
        $logger->warning('No new migrations to run.');

        $logger->line('Clearing cache...');
        $logger->success('Cache cleared!');
    }
);

Het label bijwerken

Met de label-methode werk je het label van de taak tijdens de uitvoering bij. De subLabel-methode stelt een sublabel in dat gedimd onder het label wordt getoond. Geef je een lege string door, dan wordt het sublabel gewist. Met het subLabel-argument kun je ook een initieel sublabel opgeven.

task(
    label: 'Deploying',
    callback: function ($logger) {
        $logger->subLabel('Building assets...');
        // ...
        $logger->subLabel('Running migrations...');
        // ...
        $logger->subLabel('');
    },
    subLabel: 'Preparing...'
);

Tekst streamen

Bij verwerkingen waarbij de uitvoer stapsgewijs ontstaat, zoals door AI gegenereerde responses, kun je met de partial-methode tekst stukje voor stukje streamen. Is de stream klaar, dan roep je commitPartial aan om te bevestigen.

task(
    label: 'Generating response...',
    callback: function ($logger) {
        foreach ($words as $word) {
            $logger->partial($word . ' ');
        }

        $logger->commitPartial();
    }
);

Uitvoerlimiet en de samenvatting behouden

Standaard worden maximaal 10 regels scrollende uitvoer getoond. Dit pas je aan met het limit-argument. Wil je de statusberichten na afloop van de taak op het scherm laten staan, geef dan keepSummary: true door.

task(
    label: 'Deploying',
    callback: function ($logger) {
        $logger->success('Assets built');
        $logger->success('Migrations complete');
    },
    limit: 20,
    keepSummary: true,
);

Streams

stream() toont tekst stapsgewijs in de terminal. Ideaal voor het tonen van door AI gegenereerde inhoud of data die in chunks binnenkomt.

use function Laravel\Prompts\stream;

$stream = stream();

foreach ($words as $word) {
    $stream->append($word . ' ');
    usleep(25_000); // Simuleer vertraging tussen chunks...
}

$stream->close();

De append-methode voegt tekst met een fade-in-effect aan de stream toe. Heb je alle inhoud gestreamd, roep dan close aan om de uitvoer te bevestigen en de cursor te herstellen.

Terminalbewerkingen

De terminaltitel instellen

use function Laravel\Prompts\title;

title('My Application');

Geef je een lege string door, dan wordt de standaardtitel hersteld.

title('');

De terminal wissen

use function Laravel\Prompts\clear;

clear();

Aandachtspunten voor de terminal

Terminalbreedte: als labels, opties of validatieberichten breder zijn dan het aantal kolommen van de terminal, worden ze automatisch afgekapt. Ga je uit van een terminal van 80 kolommen, houd dan maximaal 74 tekens aan als richtlijn. Terminalhoogte: bij prompts die het scroll-argument accepteren, wordt de waarde automatisch aangepast zodat alles — inclusief ruimte voor validatieberichten — binnen de hoogte van de terminal past.

Fallback

In niet-ondersteunde omgevingen (zoals Windows zonder WSL) wordt automatisch teruggevallen. Standaard worden dan de ingebouwde methodes van Laravel gebruikt, zoals $this->ask() en $this->choice().

Testen

Laravel Prompts werkt samen met Pest- en PHPUnit-tests.

use Laravel\Prompts\Prompt;

Prompt::fake(['Taylor', true]);

$name      = text('What is your name?');
$confirmed = confirm('Do you accept the terms?');

Prompt::assertOutputContains('What is your name?');

Met de Artisan-testhelpers van Laravel kun je ook assertions schrijven voor de informatiefuncties.

// 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!')
        ->expectsPromptsTable(
            headers: ['Name', 'Email'],
            rows: [
                ['Taylor Otwell', '[email protected]'],
            ]
        )
        ->assertExitCode(0);
});

// PHPUnit
public function test_report_generation(): void
{
    $this->artisan('report:generate')
        ->expectsPromptsInfo('Welcome to the application!')
        ->expectsPromptsWarning('This action cannot be undone')
        ->expectsPromptsTable(
            headers: ['Name', 'Email'],
            rows: [['Taylor Otwell', '[email protected]']]
        )
        ->assertExitCode(0);
}

Gerelateerde pagina’s

Artisan-console

Gebruik Prompts binnen Artisan-commando’s

​Inleiding

​Installatie

​Basale promptfuncties

​text — tekstinvoer

​textarea — meerregelige tekstinvoer

​number — numerieke invoer

​password — wachtwoordinvoer

​confirm — ja/nee-bevestiging

​select — keuzelijst

​multiselect — meervoudige selectie

​suggest — invoer met autocomplete

​search — dynamisch zoeken

​multisearch — dynamisch zoeken met meervoudige selectie

​pause — pauzeren

​autocomplete — inline aanvullen

​Validatie

​Formulieren

​Informatie-uitvoer

​Callouts

​Rijke inhoud

​Tabellen tonen

​Spin (laadindicator)

​Voortgangsbalken

​Taken

​Logregels uitvoeren

​Statusberichten

​Het label bijwerken

​Tekst streamen

​Uitvoerlimiet en de samenvatting behouden

​Streams

​Terminalbewerkingen

​De terminaltitel instellen

​De terminal wissen

​Aandachtspunten voor de terminal

​Fallback

​Testen

​Gerelateerde pagina’s

Artisan-console

Inleiding

Installatie

Basale promptfuncties

text — tekstinvoer

textarea — meerregelige tekstinvoer

number — numerieke invoer

password — wachtwoordinvoer

confirm — ja/nee-bevestiging

select — keuzelijst

multiselect — meervoudige selectie

suggest — invoer met autocomplete

search — dynamisch zoeken

multisearch — dynamisch zoeken met meervoudige selectie

pause — pauzeren

autocomplete — inline aanvullen

Validatie

Formulieren

Informatie-uitvoer

Callouts

Rijke inhoud

Tabellen tonen

Spin (laadindicator)

Voortgangsbalken

Taken

Logregels uitvoeren

Statusberichten

Het label bijwerken

Tekst streamen

Uitvoerlimiet en de samenvatting behouden

Streams

Terminalbewerkingen

De terminaltitel instellen

De terminal wissen

Aandachtspunten voor de terminal

Fallback

Testen

Gerelateerde pagina’s