Cli Laravel Package

Getting Started

Begin by installing the package via Composer:

composer require sebastianfeldmann/cli

The core classes are Cli (entry point), Command, and Argument. Start with a minimal CLI app:

use SebastianFeldmann\Cli\Cli;
use SebastianFeldmann\Cli\Command;

require_once 'vendor/autoload.php';

$cli = new Cli('my-tool', '1.0.0');

$cli->addCommand(new Command(
    name: 'greet',
    description: 'Say hello',
    arguments: [
        new \SebastianFeldmann\Cli\Argument\Required('name', 'Who to greet'),
    ],
    options: [
        new \SebastianFeldmann\Cli\Option\Flag('uppercase', 'Uppercase output'),
    ],
    callback: static function (Command $cmd): int {
        $name = $cmd->getArgument('name')->getValue();
        $msg = "Hello, {$name}!";
        if ($cmd->getOption('uppercase')->isSet()) {
            $msg = strtoupper($msg);
        }
        $cmd->getOutput()->writeln($msg);
        return Command::SUCCESS;
    }
));

exit($cli->run());

First use case: scaffold a CLI tool for project-specific automation (e.g., bin/my-tool generate-report).

Implementation Patterns

• Command Classes: Use a dedicated class per command (implement CommandInterface or extend AbstractCommand) for better testability and organization.
• Dependency Injection: Inject services (e.g., DB clients, processors) into command constructors — works seamlessly with existing DI containers.
• Input Validation: Leverage Argument and Option validators (e.g., ->withValidator(Validator::regex('/^[a-z]+$/'))) for early feedback.
• Output Styling: Use Output helper methods like writeln(), writeBlock() (for styled boxes), and progressBar() (for long tasks).
• Composite Commands: Register commands in batch via Cli::addCommands([...]) or group by feature (e.g., db:*, cache:*).
• Testing: Mock Input, Output, and Command — the API is designed for unit testing without CLI dependencies.

Gotchas and Tips

• Phar Caveats: If packaging as a PHAR, ensure autoloading is properly initialized (e.g., require 'phar://app.phar/vendor/autoload.php').
• Default Handler: If no command matches, Cli throws UnknownCommandException; handle gracefully with $cli->onUnknownCommand(fn($cmdName) => ...) or setCatchExceptions(true).
• Option Naming: Options use --snake-case by default; use Option::withName('camelCase') to override (not recommended for user-facing CLIs).
• Exit Codes: Return Command::SUCCESS (0) or Command::FAILURE (1) explicitly — but other codes like Command::INVALID (65) are also supported.
• No Built-in TTY Detection: For richer behavior on TTY vs non-TTY, use stream_isatty(STDOUT) manually — the library doesn’t auto-toggle verbosity.
• Extending Output: Implement OutputInterface to customize formatting (e.g., JSON output for machine consumption).