Cli Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require aura/cli
   

   No additional dependencies required.

2. First Use Case: Create a CLI command script (mycommand.php):

   <?php
   require __DIR__.'/vendor/autoload.php';
   
   use Aura\Cli\Context;
   use Aura\Cli\Stdio;
   
   $context = new Context();
   $stdio = new Stdio();
   
   // Parse arguments (e.g., `--name=John`)
   $context->parseArgs();
   
   // Access parsed arguments
   $name = $context->get('name') ?? 'World';
   $stdio->out("Hello, $name!\n");
   

3. Where to Look First:

   • README for core concepts.
   • src/Context.php and src/Stdio.php for API docs.
   • tests/ for usage examples and edge cases.

Implementation Patterns

Core Workflow

1. Argument Handling: Use Context to parse CLI arguments (supports --flag, --option=value, and positional args).

   $context = new Context();
   $context->parseArgs(); // Parses $_SERVER['argv']
   
   // Access:
   $flag = $context->get('verbose'); // bool
   $value = $context->get('name');    // string
   $positional = $context->get(0);   // first positional arg
   

2. Output Handling: Use Stdio for structured output (supports colors, formatting, and streams).

   $stdio = new Stdio();
   $stdio->out("Success!");          // Stdout
   $stdio->err("Error!");            // Stderr
   $stdio->format("User: %s", "John"); // sprintf-like formatting
   $stdio->color("red", "Error!");   // ANSI color support
   

3. Help Generation: Use Help to auto-generate CLI help text.

   use Aura\Cli\Help;
   
   $help = new Help();
   $help->addOption('--name', 'User name', 'NAME');
   $help->addFlag('--verbose', 'Enable verbose output');
   echo $help->getHelp('mycommand', 'Displays a greeting.');
   

Integration with Laravel

1. Artisan Command Integration: Extend Laravel’s Artisan::Command and use Aura\Cli for argument parsing/output.

   use Aura\Cli\Context;
   use Aura\Cli\Stdio;
   use Illuminate\Console\Command;
   
   class MyCommand extends Command
   {
       protected $stdio;
       protected $context;
   
       public function __construct()
       {
           parent::__construct();
           $this->stdio = new Stdio();
           $this->context = new Context();
       }
   
       protected function execute(InputInterface $input, OutputInterface $output)
       {
           $this->context->parseArgs();
           $name = $this->context->get('name') ?? 'World';
           $this->stdio->out("Hello, $name!\n");
       }
   
       protected function getArguments()
       {
           return [
               ['name', InputArgument::OPTIONAL, 'User name'],
           ];
       }
   }
   

2. Custom CLI Tools: Build standalone CLI tools for Laravel (e.g., deployment scripts, migrations helpers).

   // bin/laravel-deploy
   require __DIR__.'/../vendor/autoload.php';
   
   $context = new Context();
   $context->parseArgs();
   $stdio = new Stdio();
   
   if ($context->get('deploy')) {
       $stdio->out("Deploying to production...\n");
       // ... deployment logic
   }
   

3. Testing CLI Logic: Mock Context and Stdio in PHPUnit tests.

   $context = $this->createMock(Context::class);
   $context->method('get')->willReturn('test');
   
   $stdio = $this->createMock(Stdio::class);
   $stdio->expects($this->once())->method('out')->with('Hello, test!');
   
   $handler = new MyCommand($context, $stdio);
   $handler->handle();
   

Gotchas and Tips

Pitfalls

1. Argument Parsing Quirks:

   • Context does not validate argument types by default. Use get() with fallbacks or custom validation:

     $age = (int) ($context->get('age') ?? 0);
     

   • Positional arguments are accessed by index (e.g., get(0)), not by name.

2. Stdio Output Buffering:

   • Stdio::out()/err() may buffer output if not flushed explicitly. Use Stdio::flush() for real-time output:

     $stdio->out("Processing...");
     $stdio->flush();
     

3. Help Text Limitations:

   • Help does not auto-detect options/flags. You must manually add them via addOption()/addFlag().
   • No built-in support for subcommands (use a wrapper like Symfony\Component\Console).

4. PHP Version Compatibility:

   • While the package supports PHP 7.2+, some features (e.g., typed properties) may require PHP 8.0+ for full compatibility.

Debugging Tips

1. Inspect Parsed Arguments: Dump the entire Context object to debug:

   var_dump($context->getAll());
   

2. Color Output Issues:

   • ANSI colors may not render in all terminals. Test with:

     $stdio->color('red', 'Test');
     

   • Disable colors in non-interactive environments:

     $stdio->setColorEnabled(false);
     

3. Argument Conflicts:

   • Use -- to separate options from positional args if conflicts arise:

     php script.php -- --file=config.php
     

Extension Points

1. Custom Argument Parsers: Extend Context to support custom argument formats:

   class CustomContext extends Context
   {
       public function parseCustomArgs()
       {
           // Custom logic (e.g., parse YAML config files)
       }
   }
   

2. Stdio Stream Wrappers: Override Stdio to log output or redirect streams:

   class LoggingStdio extends Stdio
   {
       public function out($message)
       {
           file_put_contents('log.txt', $message);
           parent::out($message);
       }
   }
   

3. Help Text Templates: Extend Help to use custom templates or Markdown:

   class MarkdownHelp extends Help
   {
       public function getHelp(): string
       {
           return "# My Command\n\n" . $this->renderMarkdown();
       }
   }
   

4. Integration with Laravel’s Console: Use Aura\Cli alongside Laravel’s Symfony/Console for hybrid argument parsing:

   $context = new Context();
   $context->parseArgs();
   
   $input = new ArgumentInput($context->getAll());
   $output = new ConsoleOutput();