Console Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require wp-starter/console
   

   Ensure wp-starter/support, wp-starter/collections, and wp-starter/macroable are also installed (they are dependencies).

2. First Command: Register a basic command in app/Console/Kernel.php:

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

   (Note: The package lacks built-in commands; you’ll extend it.)

3. Create a Custom Command:

   php artisan make:command MyCustomCommand
   

   Extend \WpStarter\Console\Command in your new command:

   namespace App\Console\Commands;
   
   use WpStarter\Console\Command;
   
   class MyCustomCommand extends Command
   {
       protected $signature = 'my:command {argument?}';
       protected $description = 'A custom command example.';
   
       public function handle()
       {
           $this->info('Command executed!');
       }
   }
   

4. Run It:

   php artisan my:command
   

Key Entry Points

• Command Base Class: \WpStarter\Console\Command (extends Symfony’s Command).
• Macroable Support: Use wp-starter/macroable to extend commands dynamically.
• Collections Integration: Leverage wp-starter/collections for structured output (e.g., tables, lists).

Implementation Patterns

1. Command Workflows

Input/Output Handling

• Use Symfony’s built-in methods ($this->ask(), $this->confirm(), $this->table()) for user interaction.
• Example with collections:

  public function handle()
  {
      $users = collect([['id' => 1, 'name' => 'John'], ['id' => 2, 'name' => 'Jane']]);
      $this->table(['ID', 'Name'], $users->toArray());
  }
  

Artisan Integration

• Schedule Commands: Register in app/Console/Kernel.php:

  protected function schedule(Schedule $schedule)
  {
      $schedule->command('my:command')->daily();
  }
  

• Event-Driven: Trigger commands via events (e.g., Artisan::call() in controllers).

Macroable Extensions

• Add reusable methods to commands:

  \WpStarter\Console\Command::macro('logError', function ($message) {
      $this->error("[ERROR] $message");
  });
  

  Use in commands:

  $this->logError('Failed to process!');
  

2. Process Management

• Run shell commands:

  use Symfony\Component\Process\Process;
  
  $process = new Process(['ls', '-la']);
  $process->run();
  $this->info($process->getOutput());
  

  (Dependency: symfony/process is included.)

3. Configuration

• Access config via config('wpstarter.console') (if the package defines defaults).
• Override defaults in config/wpstarter.php:

  return [
      'timeout' => 30, // Example custom setting
  ];
  

4. Testing Commands

• Use Laravel’s Artisan facade in tests:

  public function test_command()
  {
      $this->artisan('my:command')
           ->expectsQuestion('Confirm?', 'yes')
           ->assertExitCode(0);
  }
  

Gotchas and Tips

Pitfalls

1. No Built-in Commands:

   • The package is a base layer; you must create all commands manually. Avoid expecting pre-built utilities.

2. Dependency Conflicts:

   • wp-starter/collections and wp-starter/support are required but may introduce version constraints. Test thoroughly.

3. Macro Scope:

   • Macros defined on \WpStarter\Console\Command are not automatically available in child classes unless explicitly extended. Re-register macros in your custom commands if needed.

4. Process Timeouts:

   • Long-running processes may hit PHP’s max_execution_time. Use symfony/process with timeouts:

     $process = new Process(['php', 'artisan', 'queue:work']);
     $process->setTimeout(60); // 60 seconds
     

5. Symfony Console Quirks:

   • Symfony’s Command class is strict about method signatures. Override configure() or execute() carefully:

     // ❌ Avoid this (will fail):
     public function execute(InputInterface $input, OutputInterface $output) { ... }
     
     // ✅ Correct:
     public function handle() { ... }
     

Debugging Tips

• Enable Verbose Output:

  php artisan my:command --verbose
  

• Log Process Output:

  $process = new Process(['some', 'command']);
  $process->run(function ($type, $buffer) {
      $this->line("<info>$buffer</info>");
  });
  

• Check for Macro Conflicts: If a macro fails silently, verify it’s registered in the correct class hierarchy.

Extension Points

1. Custom Command Helpers: Create a trait for shared logic:

   trait LogsCommands
   {
       protected function logStart()
       {
           $this->info("Starting at " . now()->toDateTimeString());
       }
   }
   

   Use in commands:

   use LogsCommands;
   
   class MyCommand extends Command
   {
       use LogsCommands;
       public function handle() { $this->logStart(); }
   }
   

2. Event-Driven Commands: Listen for events and trigger commands:

   // In an Event Service Provider
   public function boot()
   {
       event(new \App\Events\OrderProcessed());
   }
   
   // In a listener
   public function handle(OrderProcessed $event)
   {
       Artisan::call('orders:process', ['id' => $event->order->id]);
   }
   

3. Dynamic Command Registration: Register commands programmatically (e.g., from a service provider):

   $this->app->singleton(\WpStarter\Console\Command::class, function () {
       return new class extends \WpStarter\Console\Command {
           protected $signature = 'dynamic:command';
           public function handle() { $this->info('Dynamic command!'); }
       };
   });
   

Performance Considerations

• Avoid Heavy Collections in CLI: CLI tools should be fast. Use generators or chunk processing for large datasets:

  $this->table(['ID'], Model::query()->cursor()->map(fn ($item) => [$item->id]));
  

• Cache Command Results: For idempotent commands, cache outputs:

  $cacheKey = 'command:results';
  if (!$this->cache->has($cacheKey)) {
      $results = $this->fetchData();
      $this->cache->put($cacheKey, $results, now()->addHours(1));
  }