Short guide for building beautiful commands with Laravel Prompts

🔍 Overview

Laravel Prompts is a PHP package for adding beautiful and user-friendly forms to your command-line applications, with browser-like features including placeholder text and validation. It is perfect for accepting user input in your Artisan console commands, but it may also be used in any command-line PHP project.

Laravel Prompts was introduced by Jess Archer at Laracon US on July 19, 2023, and is now a built-in part of the framework. It is easy to use and can be added to your existing Artisan commands with just a few lines of code.

🚀 Installation

Laravel Prompts only requires the package to be installed. There’s no configuration file or service provider to publish.

composer require laravel/prompts

By installing using Composer, we can start building prompts for your Artisan commands.

🔨 Basic usages

If you've ever created your own Artisan commands, you'll see how easy it is to use Laravel Prompts.

Let's create a new command for this tutorial:

php artisan make:command MakeCoffeeCommand

In the old way of writing Artisan commands, we would write like this example:

namespace App\Console\Commands;

use App\Models\Coffee;
use Illuminate\Console\Command;

class MakeCoffeeCommand extends Command
{
    protected $signature = 'make:coffee';

    protected $description = 'Make some delicious coffee ☕';

    public function handle()
    {
        $name = $this->ask('What type of coffee would you like? (espresso, drip, etc.)');

        …
    }
}

You can use the functions Laravel Prompts provides and enjoy an improved output:

namespace App\Console\Commands;

use App\Models\Coffee;
use Illuminate\Console\Command;
use function Laravel\Prompts\text;

class MakeCoffeeCommand extends Command
{
    protected $signature = 'make:coffee';

    protected $description = 'Make some delicious coffee ☕';

    public function handle()
    {
        $coffeeType = text('What type of coffee would you like? (espresso, drip, etc.)');

        Coffee::create(compact('coffeeType'));

        $this->info("We made for you some $name coffee!");
    }
}

Here’s a screenshot of the command in action.

📍 Multi-select support

Let’s go even further and add type selection:

$types = multiselect(
    label: 'What type of coffee would you like',
    options: [
        'Light roast', 
        'Medium roast', 
        'Dark roast', 
        'French roast', 
        'Italian roast',
        'Espresso roast'
    ],
    scroll: 6,
    required: true,
    validate: function (array $values) {
        return ! in_array(count($values), [1, 2])
            ? 'A maximum of two roast levels can be assigned to make coffee.'
            : null;
    }
);

• Have the 6 possible roast types as options.

• The prompt is required to have an answer.

• We display 6 choices at once.

• We ensure that 1 or 2 types can be assigned.

• We leverage PHP’s named arguments to keep our code informative and omit some arguments.

Here’s how the refreshed Artisan command using Laravel Prompts looks:

📍 Searching for elements

Laravel Prompts allows you to have a lot of options for the entity to select from, the search function allows the user to type a search query to filter the results before using the arrow keys to select an option:

use function Laravel\Prompts\search;

$name = search(
    'Search for coffee type...',
    fn (string $coffeeType) => strlen($coffeeType) > 0
        ? Coffee::where('name', 'like', "%{$coffeeType}%")->pluck('name')->all()
        : []
);

Cool, right?!

📍 Adding a loading animation (spinner)

Laravel Prompts lets you use a beautiful loading animation, effortlessly. Just as with the rest of the API, it’s as simple as calling the spin() function. It serves to indicate ongoing processes and returns the callback's results upon completion:

use function Laravel\Prompts\spin;

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

The spin function needs the pcntl PHP extension to work. If you don't have it, you'll see a static spinner instead.

Now that you know the basics of Laravel Prompts, you can read the easy-to-understand documentation to learn more.

🤔 Contribute to Laravel Prompts

If you find a bug or think Laravel Prompts needs a new feature, you can send a pull request to the official repository: https://github.com/laravel/prompts