Commander Laravel Package

Getting Started

clue/commander is a lightweight library for parsing command-line arguments and matching them against defined command structures in PHP. Start by installing via Composer:

composer require clue/commander

The first use case is typically building a CLI tool: define your command tree using Command objects with positional arguments, flags, and options. The parser automatically validates and extracts inputs, making it ideal for simple scripts or micro-CLIs where full frameworks like Symfony Console would be overkill.

Implementation Patterns

Use Command::create() to build nested command hierarchies:

$cmd = Command::create('app', Command::create('run', 
    Argument::required('file'),
    Option::flag('debug'),
    Option::value('env', 'production')
));

Parse inputs with Parser::parse($argv, $cmd), which returns structured data (command path, args, flags, options). Workflows commonly involve:

• Registering commands dynamically (e.g., from a directory of handler classes).
• Embedding commander in custom shell runners or REPLs.
• Using it as a router for microservice CLI tools (e.g., service migrate, service seed).
  Integration tips: pair with clue/path-match for route-like command matching, or with clue/commander-react for async command handling.

Gotchas and Tips

• The package hasn’t seen updates since 2020—verify compatibility with PHP 8+ and modern error-reporting setups.
• Flag options (Option::flag()) require explicit true/false handling in logic, unlike Symfony’s addOption(..., InputOption::VALUE_NONE).
• Mixed-case option names (e.g., --User-Name) may cause issues; normalize names to --user-name in Option definitions.
• Extend Command for custom behavior (e.g., automatic help generation, version flags).
• Debug parsing issues by enabling Parser::setTrace(true) and inspecting the internal match trace.
• For complex tools, layer commander under a larger framework (e.g., use it only for routing, then delegate to Symfony components).