Cli Parser Laravel Package

Getting Started

Start by installing the package via Composer: composer require sebastian/cli-parser. This lightweight library (extracted from PHPUnit) offers a simple, deterministic way to parse raw $_SERVER['argv'] into structured option data—ideal for console tools where simplicity and predictability matter more than heavy-duty argument handling. Its primary entry point is the SebastianBergmann\CliParser\Parser class. The first use case is often upgrading legacy CLI scripts that previously relied on ad-hoc argv parsing, or replacing minimal homegrown logic with something well-tested and intentionally minimal (no flags like --help auto-generation, no subcommands, no option dependencies—just clean, positional + option extraction).

Implementation Patterns

Use the parser in one of two main patterns:

• Simple flag/option extraction: $parser->parse($_SERVER['argv'], ['verbose' => null, 'output:' => 'output']); → returns ['verbose' => true, 'output' => 'log.txt', ...]. The trailing : denotes options that require a value (e.g., --output=file or --output file), no trailing : means boolean flag.
• Strict positional argument capture: Pass a third parameter (e.g., ['leftovers']) to capture non-option arguments after parsing: $parser->parse($argv, $options, $positions);. This avoids manual array slicing and gives reliable access to trailing arguments.

Integration tip: Use it in CLI command runners or build scaffolds (e.g., custom dev tools, deploy scripts, or internal orchestration tools). Since it’s dependency-free and silent on validation, pair it with a schema/validation layer (e.g., opis/validation or simple manual checks) for robustness. Avoid over-engineering: this library shines in small-to-mid tools where PHPUnit-level CLI parsing is needed, but Symfony Console would be overkill.

Gotchas and Tips

• PHP version support is tight: v5.0 drops PHP 8.3; v4.0 dropped PHP 8.2. Always match the package version to your runtime. Check composer.json of your dependencies if pulling indirectly.
• No default help: It doesn’t auto-generate --help or -h. You must implement help text rendering yourself. Consider centralizing help output and reusing it.
• Ambiguous/unknown options are reported: v4.1+ prints similar valid options when an ambiguous one is passed, and v4.2+ for unknown ones (e.g., --outupt → hints --output). Use this for user feedback—don’t suppress exceptions silently.
• Options must be strings: All option definitions (keys in the spec array) must be strings. Keys like ['v' => null] work; ['v' => 1] won’t.
• Backslash escaping: Values containing spaces or special chars passed unquoted will be split. Ensure your CLI scripts always quote values when shell-invoked (standard Unix behavior).
• Not for complex CLIs: Avoid for apps needing flags, arrays (--tag=one --tag=two), or dynamic subcommands. It’s intentionally pared down. If you find yourself building workarounds, switch to Symfony/Console or Laravel Zero.