Console Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require splash/console
   

   Publish the configuration (if needed):

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

2. First Use Case Register a basic console command:

   use Splash\Console\ConsoleCommand;
   
   class ExampleCommand extends ConsoleCommand
   {
       protected $signature = 'example:greet {--name=World}';
       protected $description = 'A simple greeting command';
   
       public function handle()
       {
           $this->info("Hello, {$this->option('name')}!");
       }
   }
   

   Register the command in app/Console/Kernel.php:

   protected $commands = [
       \App\Console\Commands\ExampleCommand::class,
   ];
   

   Run it:

   php artisan example:greet --name=Laravel
   

3. Key Files to Explore

   • config/console.php (if published)
   • app/Console/Kernel.php (command registration)
   • app/Console/Commands/ (custom command directory)

Implementation Patterns

1. Command Structure

• Extend Splash\Console\ConsoleCommand for reusable base functionality (e.g., logging, input validation).
• Use $signature and $description for CLI help generation (php artisan help).
• Leverage $arguments and $options for dynamic input handling:

  protected $signature = 'user:create {name} {--email=} {--role=admin}';
  

2. Workflows

• Interactive Prompts Use ask(), confirm(), or choice() for user input:

  $name = $this->ask('What is your name?');
  if ($this->confirm('Proceed?')) {
      $this->info("Confirmed: {$name}");
  }
  

• Progress Bars For batch operations:

  $bar = $this->output->createProgressBar(100);
  for ($i = 0; $i < 100; $i++) {
      $bar->advance();
  }
  $bar->finish();
  

• Output Styling Use $this->info(), $this->error(), or $this->table() for formatted output:

  $this->table(['Name', 'Email'], [['John', '[email protected]']]);
  

3. Integration Tips

• Dependency Injection Bind services in ConsoleServiceProvider:

  $this->app->bind('custom.service', function () {
      return new CustomService();
  });
  

  Inject into commands:

  public function __construct(CustomService $service) {
      $this->service = $service;
  }
  

• Event Listeners Trigger events in commands and listen globally:

  // In command
  event(new CommandExecuted($this->getName()));
  
  // In EventServiceProvider
  protected $listen = [
      CommandExecuted::class => [CommandListener::class],
  ];
  

• Artisan Extensions Override default Artisan behavior by extending Illuminate\Console\Application:

  use Splash\Console\ConsoleApplication;
  
  class CustomArtisan extends ConsoleApplication { ... }
  

Gotchas and Tips

Pitfalls

1. Output Buffering

   • Commands may not display output immediately if buffering is enabled. Use $this->line() or $this->output->flush() to force output.
   • Example:

     $this->output->setDecorated(false); // Disable ANSI colors if needed
     

2. Signature Conflicts

   • Avoid duplicate command signatures. Use unique namespaces (e.g., vendor:package:command).

3. Error Handling

   • Uncaught exceptions in commands terminate the process. Use try/catch or throw new \Exception() for graceful failures:

     try {
         // Risky operation
     } catch (\Exception $e) {
         $this->error($e->getMessage());
     }
     

4. Configuration Overrides

   • Published config (config/console.php) may not auto-load. Ensure it’s merged in config/app.php under console:

     'console' => [
         'timeout' => env('CONSOLE_TIMEOUT', 30),
     ],
     

Debugging Tips

• Verbose Mode Enable for detailed output:

  php artisan command --verbose
  

• Logging Use Laravel’s logging facade:

  \Log::debug('Debug message', ['context' => 'command']);
  

• Command Tracing Add debug statements to track execution flow:

  $this->comment("Step 1: Starting...");
  

Extension Points

1. Custom Helpers Extend ConsoleCommand to add reusable methods:

   class BaseCommand extends ConsoleCommand
   {
       protected function logAction(string $action): void
       {
           $this->info("[{$this->getName()}] {$action}");
       }
   }
   

2. Pre/Post Hooks Use booting() and booted() in ConsoleServiceProvider for lifecycle events:

   public function booting()
   {
       $this->app->singleton('command.hook', function () {
           return new CommandHook();
       });
   }
   

3. Testing Commands Use Laravel’s Artisan facade in tests:

   public function test_example_command()
   {
       $this->artisan('example:greet --name=Test')
            ->expectsOutput('Hello, Test!')
            ->assertExitCode(0);
   }
   

4. Environment-Specific Commands Restrict commands to specific environments in Kernel.php:

   protected $shouldRunInConsole = [
       'local' => ['example:local-only'],
       'production' => ['example:prod-only'],
   ];