Cli Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require pomm-project/cli
   

   Add the service provider to config/app.php:

   Pomm\Cli\CliServiceProvider::class,
   

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

   use Pomm\Cli\Commands\BaseCommand;
   
   protected $commands = [
       \App\Console\Commands\MyCustomCommand::class,
   ];
   

3. Define a Command Extend BaseCommand in app/Console/Commands/MyCustomCommand.php:

   namespace App\Console\Commands;
   
   use Pomm\Cli\Commands\BaseCommand;
   use Symfony\Component\Console\Input\InputInterface;
   use Symfony\Component\Console\Output\OutputInterface;
   
   class MyCustomCommand extends BaseCommand
   {
       protected function configure()
       {
           $this->setName('app:my-command')
                ->setDescription('A custom Pomm CLI command');
       }
   
       protected function execute(InputInterface $input, OutputInterface $output)
       {
           $output->writeln('Hello from Pomm CLI!');
           return 0;
       }
   }
   

4. Run It

   php artisan app:my-command
   

Where to Look First

• Documentation: Check the Pomm Project docs for CLI-specific guides.
• BaseCommand: Study Pomm\Cli\Commands\BaseCommand for built-in helpers (logging, input/output, etc.).
• Symfony Console: Leverage Symfony’s InputInterface/OutputInterface for advanced CLI features.

Implementation Patterns

Common Workflows

1. Input/Output Handling Use Symfony’s InputInterface for arguments/options and OutputInterface for output:

   $name = $input->getArgument('name');
   $output->writeln("Processing: {$name}");
   

2. Logging Inject Psr\Log\LoggerInterface via constructor (Pomm CLI supports dependency injection):

   public function __construct(protected LoggerInterface $logger) {}
   
   protected function execute(InputInterface $input, OutputInterface $output)
   {
       $this->logger->info('Command started');
   }
   

3. Interactive Prompts Use Symfony’s QuestionHelper for user input:

   $helper = $this->getHelper('question');
   $question = new Question('Confirm? (y/n) ', 'n');
   $answer = $helper->ask($input, $output, $question);
   

4. Artisan Integration Call other Artisan commands from within a Pomm CLI command:

   $this->call('migrate', [
       '--force' => true,
   ]);
   

5. Event Listeners Dispatch events for post-execution hooks:

   event(new \App\Events\CommandExecuted($this->getName()));
   

Integration Tips

• Pomm Project Integration: Pair with pomm-project/core for database interactions:

  use PommProject\Pomm\Client;
  
  public function __construct(protected Client $client) {}
  

• Testing: Use Symfony\Component\Console\Tester\CommandTester for unit tests:

  $command = new MyCustomCommand();
  $commandTester = new CommandTester($command);
  $commandTester->execute(['--option' => 'value']);
  $this->assertEquals('Expected output', $commandTester->getDisplay());
  

• Configuration: Load environment-specific configs via .env or custom config files.

Gotchas and Tips

Pitfalls

1. Dependency Injection

   • Pomm CLI uses Laravel’s IoC container, but standalone usage requires manual binding:

     $container->bind(LoggerInterface::class, function () {
         return new Monolog\Logger('name');
     });
     

   • Fix: Ensure all dependencies are registered before command execution.

2. Output Buffering

   • Symfony’s OutputInterface may buffer output. Force immediate display with:

     $output->getVerbosity() === OutputInterface::VERBOSITY_NORMAL
         ? $output->writeln($message)
         : $output->write($message . PHP_EOL);
     

3. Error Handling

   • Uncaught exceptions in execute() will terminate the CLI. Use try-catch:

     try {
         // Risky operations
     } catch (\Exception $e) {
         $output->writeln('<error>Error: ' . $e->getMessage() . '</error>');
         return 1;
     }
     

4. Command Naming Conflicts

   • Avoid naming collisions with Laravel’s built-in commands (e.g., migrate). Prefix with app::

     $this->setName('app:migrate-custom');
     

Debugging Tips

• Verbose Mode: Enable with --verbose or -v for detailed logs.
• Dumping Input/Output: Use var_dump() or json_encode() for debugging:

  $output->writeln(json_encode($input->getOptions(), JSON_PRETTY_PRINT));
  

• Xdebug: Attach Xdebug to CLI scripts for step-through debugging:

  php -dxdebug.start_with_xdebug=1 artisan app:my-command
  

Extension Points

1. Custom Helpers Extend Symfony\Component\Console\Helper\HelperSet to add reusable logic:

   $this->addHelper(new class extends Helper {
       public function __invoke() { /* Custom logic */ }
   });
   

2. Command Groups Organize commands into groups for better CLI navigation:

   $this->setName('app:group:subcommand');
   

3. Progress Bars Use Symfony’s ProgressBar for long-running tasks:

   $progress = new ProgressBar($output, 100);
   for ($i = 0; $i < 100; $i++) {
       $progress->advance();
   }
   

4. Color Schemes Customize output colors via OutputInterface:

   $output->writeln('<info>Info</info>');
   $output->writeln('<comment>Comment</comment>');
   

5. Async Commands For background tasks, use Laravel’s queues or Symfony’s Process component:

   use Symfony\Component\Process\Process;
   $process = new Process(['php', 'artisan', 'queue:work']);
   $process->start();