Prompts Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/prompts
   

   No additional configuration is required—it works out-of-the-box with Laravel Artisan commands or standalone CLI scripts.

2. First Use Case: Replace a basic input() call with a Prompt for richer UX:

   use Laravel\Prompts\Prompt;
   
   $name = Prompt::text('What is your name?');
   echo "Hello, $name!";
   

3. Where to Look First:

   • Official Documentation (covers all prompt types, validation, and forms).
   • GitHub Examples (practical use cases like forms, tables, and progress bars).

Implementation Patterns

Core Workflows

1. Single Prompts: Use for one-off inputs with validation:

   $email = Prompt::email('Enter your email', required: true, validator: fn($email) => $email !== 'invalid@example.com');
   

2. Forms (Multi-Step): Group related prompts into a structured flow:

   $form = Prompt::form([
       'name' => Prompt::text('Name'),
       'age' => Prompt::number('Age', min: 18),
       'subscribe' => Prompt::confirm('Subscribe to newsletter?', default: false),
   ]);
   

3. Conditional Logic: Dynamically show/hide steps based on previous answers:

   $form = Prompt::form([
       'admin' => Prompt::confirm('Are you an admin?'),
       'admin_details' => Prompt::text('Admin details')->when(fn($admin) => $admin),
   ]);
   

4. Advanced Prompts:

   • Tables: Display data interactively:

     $users = Prompt::table('Select a user', collect([['id' => 1, 'name' => 'John']]));
     

   • Progress Bars: Visual feedback for long-running tasks:

     Prompt::progressBar('Processing...', 100)->progress(fn($bar) => $bar->advance());
     

   • Spinners & Tasks: Now more reliable on Windows/Linux without POSIX:

     Prompt::spinner('Thinking...')->spin(fn($spinner) => $spinner->stop());
     Prompt::task('Processing', fn($task) => $task->progress(100)->finish());
     

5. Integration with Artisan: Replace CLI arguments with prompts in commands:

   protected function handle(): void
   {
       $path = Prompt::path('Select a file', default: 'storage/app/file.txt');
       // Use $path...
   }
   

Best Practices

• Validation: Use closures or Laravel validators for dynamic rules:

  Prompt::text('Username', validator: fn($value) => Str::of($value)->lengthBetween(3, 20));
  

• Default Values: Set sensible defaults to reduce user effort:

  Prompt::text('Path', default: 'app/Http/Controllers');
  

• Error Handling: Wrap prompts in try-catch for graceful failures:

  try {
      $result = Prompt::confirm('Continue?');
  } catch (PromptException $e) {
      $this->error($e->getMessage());
  }
  

Gotchas and Tips

Pitfalls

1. Non-Interactive Environments:

   • Prompts fail silently in CI/CD or non-TTY contexts. Use Prompt::nonInteractive() or check Prompt::isInteractive():

     if (!Prompt::isInteractive()) {
         return; // Skip prompts in CI
     }
     

2. POSIX Dependency Fixes:

   • Spinners/Tasks: Now fall back to static rendering if the POSIX extension is unavailable (e.g., Windows without WSL). No manual intervention required—just works.
   • Test spinners/tasks on Windows/Linux without POSIX to confirm reliability.

3. Validation Edge Cases:

   • Default values may bypass validation. Explicitly validate defaults:

     Prompt::text('Age', default: '25', validator: fn($age) => (int)$age >= 18);
     

4. Multiline Inputs:

   • Textareas (Prompt::textarea()) may behave unexpectedly with special characters (e.g., emojis). Test thoroughly.

5. Logger Issues on Windows:

   • Fixed in v0.3.18: Logger no longer hangs when constructed without a socket (e.g., in Windows Laravel Sail). No action needed unless you were seeing socket-related errors.

Debugging Tips

• Hidden Inputs: Use Prompt::hidden() to mask sensitive data (e.g., passwords):

  $password = Prompt::hidden('Password');
  

• Logging: Enable debug mode for verbose output:

  Prompt::debug();
  

• Custom Styling: Override default styles via Prompt::style():

  Prompt::style('info', fn($text) => "<fg=blue>{$text}</>");
  

Extension Points

1. Custom Prompt Types: Extend Prompt to create domain-specific inputs:

   class DatabasePrompt extends Prompt
   {
       public static function database(): string
       {
           return static::select('Database', ['mysql', 'postgres', 'sqlite']);
       }
   }
   

2. Validation Helpers: Reuse validators across prompts:

   $validator = fn($value) => Str::of($value)->contains('@');
   Prompt::text('Email', validator: $validator);
   Prompt::text('Username', validator: $validator);
   

3. Localization: Translate prompts using Laravel’s translation system:

   Prompt::text(__('prompts.name'), ...);
   

Configuration Quirks

• Terminal Width: Prompts auto-detect terminal size, but force a width if needed:

  Prompt::withTerminalWidth(120);
  

• Windows Line Endings: Use Prompt::withWindowsEOL() for cross-platform compatibility:

  Prompt::withWindowsEOL(true);
  

Pro Tips

• Forms with Summary: Show collected data before submission:

  $form = Prompt::form([...])->withSummary();
  

• Dynamic Options: Populate select/multiselect from APIs or databases:

  $users = User::all()->pluck('name', 'id');
  Prompt::select('User', $users);
  

• Task Prompts: Run async tasks with progress updates (now more stable on Windows):

  Prompt::task('Processing', fn($task) => $task->progress(100)->finish());
  

• Spinners for Async Work: Use spinners for background tasks (e.g., API calls):

  Prompt::spinner('Fetching data...')->spin(fn($spinner) => $spinner->stop());
  

Cross-Platform Notes

• Windows Compatibility:
  • Spinners and tasks now render statically if POSIX is unavailable (e.g., native Windows).
  • Logger issues (socket-related) are resolved in v0.3.18.
  • Test your CLI tools on Windows to ensure spinners/tasks display as expected.