Console Helpers Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation Add the package via Composer:

   composer require tomatophp/console-helpers
   

   No additional configuration is required—it’s a drop-in helper library.

2. First Use Case: Basic Console Output Import the helper in your Artisan command or service:

   use TomatoPHP\ConsoleHelpers\Console;
   

   Use built-in methods like Console::title(), Console::section(), or Console::line():

   Console::title('My Command');
   Console::line('This is a basic line of output.');
   

3. Where to Look First

   • Documentation: Check the GitHub README (if available) or run:

     php artisan vendor:publish --provider="TomatoPHP\ConsoleHelpers\ConsoleServiceProvider"
     

     to publish the package’s config (if applicable).
   • Helper Methods: Browse the TomatoPHP\ConsoleHelpers\Console class for available methods (e.g., success(), error(), table(), progressBar()).

Implementation Patterns

Common Workflows

1. Structured Command Output Use Console::section(), Console::title(), and Console::line() to organize output hierarchically:

   Console::title('Database Migration');
   Console::section('Step 1: Backup');
   Console::line('Backing up tables...');
   

2. Progress Tracking Leverage progressBar() for long-running tasks:

   $progress = Console::progressBar(100);
   for ($i = 0; $i < 100; $i++) {
       // Simulate work
       $progress->advance();
   }
   $progress->finish();
   

3. Styling and Feedback Use color-coded methods for user feedback:

   Console::success('Migration completed!');
   Console::warning('Some tables were skipped.');
   Console::error('Failed to connect to database.');
   

4. Tables for Data Display Format tabular data with table():

   $headers = ['ID', 'Name', 'Status'];
   $rows = [[1, 'User 1', 'Active'], [2, 'User 2', 'Inactive']];
   Console::table($headers, $rows);
   

5. Interactive Prompts Use ask(), confirm(), or choice() for CLI interactions:

   $name = Console::ask('Enter your name');
   if (Console::confirm('Proceed?')) {
       Console::choice('Select an option', ['Option 1', 'Option 2']);
   }
   

6. Logging and Debugging Log messages with log() or dump variables with dump():

   Console::log('Debug info', ['key' => 'value']);
   Console::dump($variable);
   

Integration Tips

• Extend Base Commands: Override Laravel’s Handle class to include Console helpers:

  use TomatoPHP\ConsoleHelpers\Console;
  use Illuminate\Console\Command;
  
  class MyCommand extends Command {
      protected function handle() {
          Console::title('Custom Command');
          // ...
      }
  }
  

• Service Container Binding: Bind Console helpers to a service if needed:

  $this->app->singleton('console', function () {
      return new \TomatoPHP\ConsoleHelpers\Console();
  });
  

• Custom Templates: Extend the Console class to add domain-specific methods.

Gotchas and Tips

Pitfalls

1. Method Overrides Avoid naming conflicts with Laravel’s built-in methods (e.g., line() vs. newLine()). Prefer explicit helpers like Console::line() over direct Symfony\Component\Console\Output calls.

2. Progress Bar Quirks

   • Ensure the progress bar is finished ($progress->finish()) to avoid hanging output.
   • For large loops, use sleep() or chunk processing to prevent UI lag:

     for ($i = 0; $i < 1000; $i++) {
         if ($i % 10 === 0) $progress->advance();
     }
     

3. Interactive Prompts in Non-TTY Prompts like ask() or confirm() may fail in non-interactive environments (e.g., CI/CD). Use fallbacks:

   if (Console::isInteractive()) {
       $input = Console::ask('Question?');
   } else {
       $input = 'default_value';
   }
   

4. Table Formatting

   • Long strings in tables may truncate. Use wordwrap() or limit column width:

     $rows = array_map(function ($row) {
         $row[1] = wordwrap($row[1], 20, "\n", true);
         return $row;
     }, $rows);
     

   • Ensure headers and rows align in length to avoid misaligned tables.

5. Deprecation Risks The package is lightweight but lacks active maintenance. Test critical features across Laravel versions (e.g., 8/9/10) for compatibility.

Debugging Tips

• Enable Verbose Output: Use Console::verbose() to log detailed steps:

  Console::verbose('Verbose details', ['data' => 'value']);
  

• Check for Typos: Helper methods are case-sensitive (e.g., Console::SUCCESS() vs. Console::success()).
• Inspect Output Buffering: If output appears delayed, flush manually:

  Console::output()->flush();
  

Extension Points

1. Custom Helpers Extend the Console class to add domain-specific methods:

   class CustomConsole extends \TomatoPHP\ConsoleHelpers\Console {
       public function customMethod() {
           $this->line('Custom output');
       }
   }
   

   Bind it in a service provider:

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

2. Override Templates Modify the Console class to change default styles (e.g., colors, formats) by overriding protected methods like getStyle().

3. Add New Prompt Types Extend the Prompt class to support custom input validation or formatting.

4. Integrate with Laravel Logging Pipe Console::log() output to Laravel’s log channels by binding a custom handler:

   Console::setLogger($this->app->make('log'));