Prompts Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/prompts
   

   No additional configuration is required—just use the package in your Artisan commands or CLI scripts.

2. First Use Case: Replace basic Symfony\Component\Console\Question\Question with Prompt\Prompt for richer input handling.

   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 and helpers).
   • GitHub Examples (practical use cases).
   • Prompt::* static methods (e.g., Prompt::select(), Prompt::confirm()).

Implementation Patterns

Core Workflows

1. Interactive Forms: Use Prompt::form() to group related inputs into a multi-step UI:

   $result = Prompt::form([
       'name' => Prompt::text('Name'),
       'age'  => Prompt::number('Age', min: 18),
       'admin' => Prompt::confirm('Admin?', default: false),
   ]);
   

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

   $form = Prompt::form([
       'role' => Prompt::select('Role', ['dev', 'designer']),
       'framework' => Prompt::select('Framework')->when('role', 'dev'),
   ]);
   

3. Data Validation: Validate inputs inline with Laravel-style rules:

   $email = Prompt::text('Email', validator: fn ($email) =>
       Validator::make(['email' => $email], ['email' => 'required|email'])
   );
   

4. Progress Tracking: Use Prompt::progress() for long-running tasks:

   Prompt::progress()->spin('Processing...', fn () => sleep(3));
   

Integration Tips

• Artisan Commands: Replace $this->ask() with Prompt::text() for consistency and richer UX.

  protected $signature = 'user:create';
  public function handle(): void
  {
      $name = Prompt::text('Name');
      // ...
  }
  

• Non-Interactive Mode: Disable prompts in CI/CD with Prompt::nonInteractive():

  if (Prompt::nonInteractive()) {
      $name = 'default-name';
  } else {
      $name = Prompt::text('Name');
  }
  

• Custom Helpers: Extend with reusable components (e.g., Prompt::helper('table', fn () => ...)).

Gotchas and Tips

Pitfalls

1. Default Values:

   • Falsy defaults (e.g., 0, false) may not work as expected in select prompts. Use null or explicit strings.
   • Fix: Prompt::select('Option', ['a', 'b'], default: 'a').

2. Validation Quirks:

   • Non-closure validators (e.g., fn ($val) => $val > 0) may fail silently. Use closures:

     validator: fn ($val) => $val > 0 ? true : 'Must be > 0'
     

3. Multibyte Characters:

   • Textareas with non-ASCII text may misbehave with arrow keys. Test thoroughly in your target environments.

4. Windows Line Endings:

   • Progress bars/spinners may render incorrectly. Use Prompt::clear() to reset the terminal if needed.

Debugging

• Silent Failures: Wrap prompts in try-catch to handle terminal read errors gracefully:

  try {
      $input = Prompt::text('Input');
  } catch (\Throwable $e) {
      $input = 'fallback';
  }
  

• Non-Interactive Mode: Ensure your app checks Prompt::nonInteractive() early to avoid hangs in CI.

Extension Points

1. Custom Prompt Types: Extend Laravel\Prompts\Prompt to add domain-specific inputs (e.g., Prompt::color()).

2. Styling: Override default styles via Prompt::style() or Symfony’s NamedStyle:

   Prompt::style('error', fn () => '<fg=red>Error</>');
   

3. Testing: Mock prompts in tests using Prompt::fake():

   Prompt::fake(['name' => 'test']);
   $name = Prompt::text('Name'); // Returns 'test'
   

Pro Tips

• Dynamic Options: Use Prompt::select() with a closure for runtime-generated options:

  Prompt::select('User', fn () => User::all()->pluck('name', 'id'))
  

• Multi-Select Shortcuts: Allow "Select All" with Prompt::multiselect(..., allowSelectAll: true).

• Progress Bars: Update dynamically with Prompt::progress()->spin('Task', fn () => $this->process()).

```markdown
### Config Quirks
- **No Config File**: Laravel Prompts is zero-config. All behavior is controlled via method arguments.
- **Global Defaults**: Set defaults in a service provider if reused across commands:
  ```php
  Prompt::macro('custom', fn ($question, $default = null) =>
      Prompt::text($question, default: $default, validator: fn ($val) => $val !== 'invalid')
  );