Prompts

• Introduzione
• Installazione
• Prompt Disponibili
• Trasformazione dell’input prima della validazione
• Form
• Messaggi Informativi
• Tabelle
• Spin
• Barre di avanzamento
• Pulire il Terminale
• Considerazioni sul Terminale
• Ambienti non supportati e fallback

Introduzione

Laravel Prompts è un package PHP per aggiungere moduli belli e facili da usare alle tue applicazioni da riga di comando, con funzionalità simili ai browser, come testo segnaposto e validazione.

Laravel Prompts è perfetto per accettare input degli utenti nei tuoi comandi della console Artisan, ma può essere utilizzato anche in qualsiasi progetto PHP da riga di comando.

Laravel Prompts supporta macOS, Linux e Windows con WSL. Per maggiori informazioni, consulta la nostra documentazione su ambienti non supportati e soluzioni alternative.

Installazione

Laravel Prompts è già incluso nell’ultima versione di Laravel.

Laravel Prompts può essere installato anche nei tuoi altri progetti PHP utilizzando il gestore di pacchetti Composer:

composer require laravel/prompts

Prompt Disponibili

Testo

La funzione text chiederà all’utente la domanda fornita, accetterà il suo input e poi lo restituirà:

use function Laravel\Prompts\text;

$name = text('Qual è il tuo nome?');

Puoi anche includere un testo segnaposto, un valore predefinito e un suggerimento informativo:

$name = text(
    label: 'Qual è il tuo nome?',
    placeholder: 'Es. Taylor Otwell',
    default: $user?->name,
    hint: 'Questo verrà mostrato sul tuo profilo.'
);

Valori Richiesti

Se è necessario inserire un valore, puoi passare l’argomento required:

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

Se vuoi personalizzare il messaggio di validazione, puoi anche passare una stringa:

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

Validazione Aggiuntiva

Infine, se desideri eseguire una logica di validazione aggiuntiva, puoi passare una closure all’argomento 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
    }
);

La closure riceverà il valore inserito e potrà restituire un messaggio di errore, oppure null se la validazione ha successo.

In alternativa, puoi sfruttare la potenza del validator di Laravel. Per farlo, fornisci un array contenente il nome dell’attributo e le regole di validazione desiderate all’argomento validate:

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

Textarea

La funzione textarea mostrerà all’utente la domanda specificata, accetterà il suo input tramite una textarea multi-linea e poi lo restituirà:

use function Laravel\Prompts\textarea;

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

Puoi anche includere un testo segnaposto, un valore predefinito e un suggerimento informativo:

$story = textarea(
    label: 'Tell me a story.',
    placeholder: 'This is a story about...',
    hint: 'This will be displayed on your profile.'
);

Valori Richiesti

Se richiedi che un valore venga inserito, puoi passare l’argomento required:

$story = textarea(
    label: 'Raccontami una storia.',
    required: true
);

Se desideri personalizzare il messaggio di validazione, puoi anche passare una stringa:

$story = textarea(
    label: 'Raccontami una storia.',
    required: 'Una storia è richiesta.'
);

Validazione Aggiuntiva

Infine, se desideri eseguire una logica di validazione aggiuntiva, puoi passare una closure all’argomento validate:

$story = textarea(
    label: 'Raccontami una storia.',
    validate: fn (string $value) => match (true) {
        strlen($value) < 250 => 'La storia deve avere almeno 250 caratteri.',
        strlen($value) > 10000 => 'La storia non deve superare i 10.000 caratteri.',
        default => null
    }
);

La closure riceverà il valore inserito e potrà restituire un messaggio di errore o null se la validazione ha successo.

In alternativa, puoi sfruttare la potenza del validator di Laravel. Per farlo, fornisci un array contenente il nome dell’attributo e le regole di validazione desiderate all’argomento validate:

$story = textarea(
    label: 'Raccontami una storia.',
    validate: ['story' => 'required|max:10000']
);

Password

La funzione password è simile alla funzione text, ma l’input dell’utente viene mascherato mentre digita nella console. Questo è utile quando si richiedono informazioni sensibili come le password:

use function Laravel\Prompts\password;

$password = password('Qual è la tua password?');

Puoi anche includere un testo segnaposto e un suggerimento informativo:

$password = password(
    label: 'Qual è la tua password?',
    placeholder: 'password',
    hint: 'Almeno 8 caratteri.'
);

Valori Richiesti

Se è necessario inserire un valore, puoi passare l’argomento required:

$password = password(
    label: 'Qual è la tua password?',
    required: true
);

Se desideri personalizzare il messaggio di validazione, puoi anche passare una stringa:

$password = password(
    label: 'Qual è la tua password?',
    required: 'La password è richiesta.'
);

Validazione Aggiuntiva

Infine, se desideri eseguire una logica di validazione aggiuntiva, puoi passare una closure all’argomento 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
    }
);

La closure riceverà il valore inserito e può restituire un messaggio di errore, oppure null se la validazione ha successo.

In alternativa, puoi sfruttare il potere del validator di Laravel. Per fare ciò, fornisci un array contenente il nome dell’attributo e le regole di validazione desiderate all’argomento validate:

$password = password(
    label: 'What is your password?',
    validate: ['password' => 'min:8']
);

Conferma

Se hai bisogno di chiedere all’utente una conferma "sì o no", puoi usare la funzione confirm. Gli utenti possono usare i tasti freccia o premere y o n per selezionare la loro risposta. Questa funzione restituirà true o false.

use function Laravel\Prompts\confirm;

$confirmed = confirm('Accetti i termini?');

Puoi anche includere un valore predefinito, una formulazione personalizzata per le etichette "Yes" e "No", e un suggerimento informativo:

$confirmed = confirm(
    label: 'Accetti i termini?',
    default: false,
    yes: 'Accetto',
    no: 'Rifiuto',
    hint: 'I termini devono essere accettati per continuare.'
);

Richiedere "Sì"

Se necessario, puoi richiedere ai tuoi utenti di selezionare "Sì" passando l’argomento required:

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

Se desideri personalizzare il messaggio di validazione, puoi anche passare una stringa:

$confirmed = confirm(
    label: 'Do you accept the terms?',
    required: 'You must accept the terms to continue.'
);

Select

Se hai bisogno che l’utente selezioni da un insieme di opzioni predefinite, puoi utilizzare la funzione select:

use function Laravel\Prompts\select;

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

Puoi anche specificare l’opzione predefinita e un suggerimento informativo:

$role = select(
    label: 'What role should the user have?',
    options: ['Member', 'Contributor', 'Owner'],
    default: 'Owner',
    hint: 'The role may be changed at any time.'
);

Puoi inoltre passare un array associativo all’argomento options per ottenere la chiave selezionata invece del suo valore:

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

Fino a cinque opzioni saranno visualizzate prima che la lista inizi a scorrere. Puoi personalizzare questo passando l’argomento scroll:

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

Validazione Aggiuntiva

A differenza delle altre funzioni prompt, la funzione select non accetta l’argomento required perché non è possibile non selezionare nulla. Tuttavia, puoi passare una closure all’argomento validate se devi presentare un’opzione ma impedirne la selezione:

$role = select(
    label: 'Quale ruolo dovrebbe avere l\'utente?',
    options: [
        'member' => 'Member',
        'contributor' => 'Contributor',
        'owner' => 'Owner',
    ],
    validate: fn (string $value) =>
        $value === 'owner' && User::where('role', 'owner')->exists()
            ? 'Esiste già un proprietario.'
            : null
);

Se l’argomento options è un array associativo, la closure riceverà la chiave selezionata, altrimenti riceverà il valore selezionato. La closure può restituire un messaggio di errore o null se la validazione passa.

Multi-select

Se hai bisogno che l’utente possa selezionare più opzioni, puoi usare la funzione multiselect:

use function Laravel\Prompts\multiselect;

$permissions = multiselect(
    label: 'Quali permessi devono essere assegnati?',
    options: ['Read', 'Create', 'Update', 'Delete']
);

Puoi anche specificare scelte predefinite e un suggerimento informativo:

use function Laravel\Prompts\multiselect;

$permissions = multiselect(
    label: 'Quali permessi devono essere assegnati?',
    options: ['Read', 'Create', 'Update', 'Delete'],
    default: ['Read', 'Create'],
    hint: 'I permessi possono essere aggiornati in qualsiasi momento.'
);

Puoi anche passare un array associativo all’argomento options per restituire le chiavi delle opzioni selezionate invece dei loro valori:

$permissions = multiselect(
    label: 'Quali permessi devono essere assegnati?',
    options: [
        'read' => 'Read',
        'create' => 'Create',
        'update' => 'Update',
        'delete' => 'Delete',
    ],
    default: ['read', 'create']
);

Verranno mostrate fino a cinque opzioni prima che l’elenco inizi a scorrere. Puoi personalizzare questo passando l’argomento scroll:

$categories = multiselect(
    label: 'Quali categorie devono essere assegnate?',
    options: Category::pluck('name', 'id'),
    scroll: 10
);

Impostare come obbligatorio

Di default, l’utente può selezionare zero o più opzioni. Puoi passare l’argomento required per richiedere invece una o più opzioni:

$categories = multiselect(
    label: 'Quali categorie devono essere assegnate?',
    options: Category::pluck('name', 'id'),
    required: true
);

Se desideri personalizzare il messaggio di validazione, puoi fornire una stringa all’argomento required:

$categories = multiselect(
    label: 'Quali categorie devono essere assegnate?',
    options: Category::pluck('name', 'id'),
    required: 'Devi selezionare almeno una categoria'
);

Validazione Aggiuntiva

Puoi passare una closure all’argomento validate se hai bisogno di presentare un’opzione ma impedirne la selezione:

$permissions = multiselect(
    label: 'Quali permessi dovrebbe avere l\'utente?',
    options: [
        'read' => 'Read',
        'create' => 'Create',
        'update' => 'Update',
        'delete' => 'Delete',
    ],
    validate: fn (array $values) => ! in_array('read', $values)
        ? 'Tutti gli utenti richiedono il permesso di lettura.'
        : null
);

Se l’argomento options è un array associativo, la closure riceverà le chiavi selezionate, altrimenti riceverà i valori selezionati. La closure può restituire un messaggio di errore o null se la validazione ha successo.

Suggerisci

La funzione suggest può essere utilizzata per fornire l’auto-completamento delle scelte possibili. L’utente può comunque fornire qualsiasi risposta, indipendentemente dai suggerimenti di auto-completamento:

use function Laravel\Prompts\suggest;

$name = suggest('Qual è il tuo nome?', ['Taylor', 'Dayle']);

In alternativa, puoi passare una closure come secondo argomento alla funzione suggest. La closure verrà chiamata ogni volta che l’utente digita un carattere di input. La closure dovrebbe accettare un parametro stringa contenente l’input dell’utente finora e restituire un array di opzioni per l’auto-completamento:

$name = suggest(
    label: 'Qual è il tuo nome?',
    options: fn ($value) => collect(['Taylor', 'Dayle'])
        ->filter(fn ($name) => Str::contains($name, $value, ignoreCase: true))
)

Puoi anche includere un testo segnaposto, un valore predefinito e un suggerimento informativo:

$name = suggest(
    label: 'Qual è il tuo nome?',
    options: ['Taylor', 'Dayle'],
    placeholder: 'Es. Taylor',
    default: $user?->name,
    hint: 'Questo sarà mostrato sul tuo profilo.'
);

Valori Richiesti

Se è necessario inserire un valore, puoi passare l’argomento required:

$name = suggest(
    label: 'Qual è il tuo nome?',
    options: ['Taylor', 'Dayle'],
    required: true
);

Se desideri personalizzare il messaggio di validazione, puoi anche passare una stringa:

$name = suggest(
    label: 'Qual è il tuo nome?',
    options: ['Taylor', 'Dayle'],
    required: 'Il tuo nome è obbligatorio.'
);

Validazione Aggiuntiva

Infine, se desideri eseguire una logica di validazione aggiuntiva, puoi passare una closure all’argomento validate:

$name = suggest(
    label: 'Qual è il tuo nome?',
    options: ['Taylor', 'Dayle'],
    validate: fn (string $value) => match (true) {
        strlen($value) < 3 => 'Il nome deve avere almeno 3 caratteri.',
        strlen($value) > 255 => 'Il nome non deve superare i 255 caratteri.',
        default => null
    }
);

La closure riceverà il valore inserito e può restituire un messaggio di errore, oppure null se la validazione ha successo.

In alternativa, puoi sfruttare la potenza del validator di Laravel. Per farlo, fornisci un array contenente il nome dell’attributo e le regole di validazione desiderate all’argomento validate:

$name = suggest(
    label: 'Qual è il tuo nome?',
    options: ['Taylor', 'Dayle'],
    validate: ['name' => 'required|min:3|max:255']
);

Ricerca

Se hai molte opzioni tra cui l’utente può scegliere, la funzione search permette all’utente di digitare una query di ricerca per filtrare i risultati prima di usare i tasti freccia per selezionare un’opzione:

use function Laravel\Prompts\search;

$id = 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()
        : []
);

La closure riceverà il testo digitato dall’utente fino a quel momento e deve restituire un array di opzioni. Se restituisci un array associativo, verrà restituita la chiave dell’opzione selezionata, altrimenti verrà restituito il suo valore.

Quando filtri un array in cui intendi restituire il valore, dovresti usare la funzione array_values o il metodo values della Collection per assicurarti che l’array non diventi associativo:

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

$selected = search(
    label: 'Search for the user that should receive the mail',
    options: fn (string $value) => $names
        ->filter(fn ($name) => Str::contains($name, $value, ignoreCase: true))
        ->values()
        ->all(),
);

Puoi anche includere del testo segnaposto e un suggerimento informativo:

$id = search(
    label: 'Search for the user that should receive the mail',
    placeholder: 'Ad es. Taylor Otwell',
    options: fn (string $value) => strlen($value) > 0
        ? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    hint: 'L\'utente riceverà un\'email immediatamente.'
);

Fino a cinque opzioni saranno visualizzate prima che la lista inizi a scorrere. Puoi personalizzare questo passando l’argomento scroll:

$id = 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()
        : [],
    scroll: 10
);

Validazione Aggiuntiva

Se desideri eseguire una logica di validazione aggiuntiva, puoi passare una closure all’argomento validate:

$id = 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()
        : [],
    validate: function (int|string $value) {
        $user = User::findOrFail($value);

        if ($user->opted_out) {
            return 'This user has opted-out of receiving mail.';
        }
    }
);

Se la closure options restituisce un array associativo, la closure validate riceverà la chiave selezionata, altrimenti riceverà il valore selezionato. La closure può restituire un messaggio di errore o null se la validazione viene superata.

Multi-search

Se hai molte opzioni ricercabili e devi consentire all’utente di selezionare più elementi, la funzione multisearch permette all’utente di digitare una query di ricerca per filtrare i risultati prima di usare i tasti freccia e la barra spaziatrice per selezionare le opzioni:

use function Laravel\Prompts\multisearch;

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

La closure riceverà il testo che l’utente ha digitato finora e deve restituire un array di opzioni. Se restituisci un array associativo, verranno restituite le chiavi delle opzioni selezionate; altrimenti, verranno restituiti i loro valori.

Quando filtri un array in cui intendi restituire il valore, dovresti usare la funzione array_values o il metodo values della Collection per assicurarti che l’array non diventi associativo:

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

$selected = multisearch(
    label: 'Search for the users that should receive the mail',
    options: fn (string $value) => $names
        ->filter(fn ($name) => Str::contains($name, $value, ignoreCase: true))
        ->values()
        ->all(),
);

Puoi anche includere un testo segnaposto e un suggerimento informativo:

$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::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
        : [],
    hint: 'The user will receive an email immediately.'
);

Fino a cinque opzioni saranno visualizzate prima che la lista inizi a scorrere. Puoi personalizzare questo comportamento fornendo l’argomento scroll:

$ids = 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()
        : [],
    scroll: 10
);

Richiedere un Valore

Di default, l’utente può selezionare zero o più opzioni. Puoi passare l’argomento required per richiedere una o più opzioni invece:

$ids = 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()
        : [],
    required: true
);

Se vuoi personalizzare il messaggio di validazione, puoi anche fornire una stringa all’argomento required:

$ids = 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()
        : [],
    required: 'Devi selezionare almeno un utente.'
);

Validazione Aggiuntiva

Se desideri eseguire una logica di validazione aggiuntiva, puoi passare una closure all’argomento validate:

$ids = 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()
        : [],
    validate: function (array $values) {
        $optedOut = User::whereLike('name', '%a%')->findMany($values);

        if ($optedOut->isNotEmpty()) {
            return $optedOut->pluck('name')->join(', ', ', and ').' have opted out.';
        }
    }
);

Se la closure options restituisce un array associativo, allora la closure riceverà le chiavi selezionate; altrimenti, riceverà i valori selezionati. La closure può restituire un messaggio di errore o null se la validazione è superata.

Pause

La funzione pause può essere utilizzata per mostrare un testo informativo all’utente e attendere che confermi di voler procedere premendo il tasto Invio / Return:

use function Laravel\Prompts\pause;

pause('Premi INVIO per continuare.');

Trasformazione dell’input prima della validazione

A volte potresti voler trasformare l’input prima che venga eseguita la validazione. Ad esempio, potresti voler rimuovere gli spazi bianchi da qualsiasi stringa fornita. Per fare ciò, molte delle funzioni di prompt offrono un argomento transform, che accetta una closure:

$name = text(
    label: 'What is your name?',
    transform: fn (string $value) => trim($value),
    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
    }
);

Form

Spesso, avrai più prompt che verranno visualizzati in sequenza per raccogliere informazioni prima di eseguire azioni aggiuntive. Puoi usare la funzione form per creare un insieme di prompt raggruppati che l’utente deve completare:

use function Laravel\Prompts\form;

$responses = form()
    ->text('Qual è il tuo nome?', required: true)
    ->password('Qual è la tua password?', validate: ['password' => 'min:8'])
    ->confirm('Accetti i termini?')
    ->submit();

Il metodo submit restituirà un array indicizzato numericamente contenente tutte le risposte dai prompt del form. Tuttavia, puoi fornire un nome per ogni prompt tramite l’argomento name. Quando viene fornito un nome, la risposta del prompt nominato può essere accessa tramite quel nome:

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

$responses = form()
    ->text('Qual è il tuo nome?', required: true, name: 'name')
    ->password(
        label: 'Qual è la tua password?',
        validate: ['password' => 'min:8'],
        name: 'password'
    )
    ->confirm('Accetti i termini?')
    ->submit();

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

Il principale vantaggio dell’usare la funzione form è la possibilità per l’utente di tornare ai prompt precedenti nel form usando CTRL + U. Questo permette all’utente di correggere errori o modificare selezioni senza dover cancellare e ricominciare l’intero form.

Se hai bisogno di un controllo più dettagliato su un prompt in un form, puoi invocare il metodo add invece di chiamare direttamente una delle funzioni prompt. Il metodo add riceve tutte le risposte precedenti fornite dall’utente:

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

$responses = form()
    ->text('Qual è il tuo nome?', required: true, name: 'name')
    ->add(function ($responses) {
        return text("Quanti anni hai, {$responses['name']}?");
    }, name: 'age')
    ->submit();

outro("Il tuo nome è {$responses['name']} e hai {$responses['age']} anni.");

Messaggi Informativi

Le funzioni note, info, warning, error e alert possono essere usate per mostrare messaggi informativi:

use function Laravel\Prompts\info;

info('Package installed successfully.');

Tabelle

La funzione table consente di visualizzare facilmente più righe e colonne di dati. Basta fornire i nomi delle colonne e i dati della tabella:

use function Laravel\Prompts\table;

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

Spin

La funzione spin mostra uno spinner insieme a un messaggio opzionale mentre esegue una callback specificata. Serve per indicare processi in corso e restituisce i risultati della callback al completamento:

use function Laravel\Prompts\spin;

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

La funzione spin richiede l’estensione PHP pcntl per animare lo spinner. Quando questa estensione non è disponibile, apparirà invece una versione statica dello spinner.

Barre di avanzamento

Per attività che richiedono molto tempo, può essere utile mostrare una barra di avanzamento che informa gli utenti su quanto sia completata l’attività. Usando la funzione progress, Laravel mostrerà una barra di avanzamento e avanzerà il suo progresso ad ogni iterazione su un valore iterabile dato:

use function Laravel\Prompts\progress;

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

La funzione progress funziona come una funzione di mappatura e restituirà un array contenente il valore restituito da ogni iterazione del tuo callback.

Il callback può anche accettare l’istanza Laravel\Prompts\Progress, permettendoti di modificare l’etichetta e l’indicazione ad ogni iterazione:

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

A volte, potresti aver bisogno di un controllo più manuale su come avanzare una barra di avanzamento. Prima, definisci il numero totale di passaggi che il processo itera. Poi, avanza la barra di avanzamento tramite il metodo advance dopo aver processato ogni elemento:

$progress = progress(label: 'Updating users', steps: 10);

$users = User::all();

$progress->start();

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

    $progress->advance();
}

$progress->finish();

Pulire il Terminale

La funzione clear può essere usata per pulire il terminale dell’utente:

use function Laravel\Prompts\clear;

clear();

Considerazioni sul Terminale

Larghezza del Terminale

Se la lunghezza di qualsiasi label, option o messaggio di validazione supera il numero di "colonne" nel terminale dell’utente, verrà automaticamente troncata per adattarsi. Considera di ridurre la lunghezza di queste stringhe se i tuoi utenti potrebbero usare terminali più stretti. Una lunghezza massima generalmente sicura è di 74 caratteri per supportare un terminale da 80 caratteri.

Altezza del Terminale

Per qualsiasi prompt che accetta l’argomento scroll, il valore configurato verrà automaticamente ridotto per adattarsi all’altezza del terminale dell’utente, inclusa lo spazio per un messaggio di validazione.

Ambienti non supportati e fallback

Laravel Prompts supporta macOS, Linux e Windows con WSL. A causa delle limitazioni della versione di PHP per Windows, attualmente non è possibile utilizzare Laravel Prompts su Windows al di fuori di WSL.

Per questo motivo, Laravel Prompts prevede un fallback a un’implementazione alternativa come il Symfony Console Question Helper.

Quando utilizzi Laravel Prompts con il framework Laravel, i fallback per ogni prompt sono stati configurati automaticamente e saranno abilitati negli ambienti non supportati.

Condizioni di fallback

Se non stai usando Laravel o hai bisogno di personalizzare quando viene utilizzato il comportamento di fallback, puoi passare un booleano al metodo statico fallbackWhen della classe Prompt:

use Laravel\Prompts\Prompt;

Prompt::fallbackWhen(
    ! $input->isInteractive() || windows_os() || app()->runningUnitTests()
);

Comportamento di fallback

Se non stai usando Laravel o hai bisogno di personalizzare il comportamento di fallback, puoi passare una closure al metodo statico fallbackUsing su ogni classe di prompt:

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

I fallback devono essere configurati individualmente per ogni classe di prompt. La closure riceverà un’istanza della classe di prompt e deve restituire un tipo appropriato per il prompt.