Console Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require laranail/console
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Laranail\Console\ConsoleServiceProvider"
   

2. First Use Case: Basic Output Inject the Console facade into a command or service:

   use Laranail\Console\Console;
   
   public function handle()
   {
       Console::info('Hello, Laravel!');
       Console::success('Task completed!');
   }
   

3. Key Entry Points

   • Fluent Output: Console::line(), Console::table(), Console::tree()
   • Prompts: Console::prompt(), Console::confirm()
   • Forms: Console::form()->submit()
   • Progress: Console::progressBar()

   Check the documentation for API reference.

Implementation Patterns

Core Workflows

1. Structured CLI Output Use Console::table() for tabular data (e.g., database records):

   $users = User::all();
   Console::table(['ID', 'Name', 'Email'], $users->toArray());
   

2. Interactive Prompts Build dynamic commands with Console::prompt():

   $name = Console::prompt('Enter your name');
   $confirm = Console::confirm('Proceed?', false);
   

3. Forms for Complex Input Validate user input via forms:

   $result = Console::form()
       ->text('name', 'Name', ['required'])
       ->email('email', 'Email')
       ->submit();
   
   if ($result->valid()) {
       $data = $result->data();
   }
   

4. Progress Tracking Visualize long-running tasks:

   $bar = Console::progressBar(100);
   for ($i = 0; $i < 100; $i++) {
       $bar->advance();
   }
   

Integration Tips

• Commands: Extend Laranail\Console\ConsoleCommand for pre-configured output.
• Services: Use dependency injection to reuse Console across classes.
• Theming: Customize colors via config (config/console.php):

  'colors' => [
      'info' => '#3498db',
      'error' => '#e74c3c',
  ],
  

• Localization: Override messages in lang/vendor/console.php.

Gotchas and Tips

Pitfalls

1. Progress Bar Stuck

   • Cause: Forgetting to call $bar->finish().
   • Fix: Always wrap progress bars in try-finally:

     $bar = Console::progressBar(100);
     try {
         // Work...
     } finally {
         $bar->finish();
     }
     

2. Prompt Input Truncation

   • Cause: Long input in Console::prompt() may cut off.
   • Fix: Use Console::input() for multi-line input or adjust terminal width.

3. Form Validation Errors

   • Cause: Custom validators may not display errors clearly.
   • Fix: Use ->error() in forms:

     $form->text('age', 'Age')->rule('numeric|min:18')
          ->error('Age must be 18+');
     

4. Color Inconsistencies

   • Cause: Terminals may not support all ANSI colors.
   • Fix: Fallback to basic colors in config/console.php:

     'fallback_colors' => true,
     

Debugging

• Disable Output: Temporarily set Console::disableOutput() to debug logic without clutter.
• Log Raw Output: Use Console::raw('{output}')->log() to inspect formatted strings.
• Check for Typos: Validate method names (e.g., Console::table() vs Console::tabular()).

Extension Points

1. Custom Output Styles Extend Laranail\Console\Output\Style:

   class CustomStyle extends Style {
       public function custom($text) {
           return $this->wrap($text, '<fg=yellow>...</>');
       }
   }
   

2. Add Prompt Types Implement Laranail\Console\Prompt\PromptInterface for custom prompts (e.g., password with masking).

3. Override Defaults Bind custom implementations in ConsoleServiceProvider:

   $this->app->bind('console', function () {
       return new CustomConsole();
   });
   

4. Tree/Box Customization Modify templates in resources/views/vendor/console/ (if using Blade-like syntax).