Caplet Laravel Package

Getting Started

Start by requiring the package via Composer:

composer require pmjones/caplet

Then create a new Caplet instance and add commands using addCommand(). Each command is a closure or invokable object implementing the Caplet\Command interface (typically with __invoke(Input $input, Output $output)). The basic pattern:

use Caplet\Caplet;
use Caplet\Input;
use Caplet\Output;

$caplet = new Caplet();

$caplet->addCommand('hello', function (Input $input, Output $output) {
    $name = $input->getArgument('name') ?? 'World';
    $output->writeln("Hello, {$name}!");
});

$caplet->run();

Run it from CLI: php your-script.php hello --name=Taylor. Use --help to see auto-generated usage.

Implementation Patterns

• Command Modularity: Break logic into small, single-responsibility commands (e.g., build, test, deploy). Each command handles one task cleanly.
• Input Handling: Use $input->getArgument(), $input->getOption(), and $input->hasOption() to extract CLI parameters. Define argument/option defaults in the command or at registration via addCommand('cmd', $callback, ['arguments' => [...], 'options' => [...]]).
• Testable I/O: Inject Output (with methods like write(), writeln(), error()) instead of echoing directly. For unit tests, use Output\Buffer or Output\Null to capture or suppress output.
• Composite Tools: Chain multiple caplets into a single CLI by grouping under namespaces or subcommands (e.g., db:migrate, db:seed) using a top-level Caplet and nested registration.
• Exit Codes: Return an integer from a command to signal exit status (e.g., 0 for success, 1 for error); Caplet honors this.

Gotchas and Tips

• Missing Dependency Injection: Caplet is deliberately minimal — no built-in DI container. Use closures to inject dependencies manually (e.g., fn($in, $out) => (new MyCommand($service))->run($in, $out)).
• Output Buffering: The Output interface does not auto-flush; to force immediate output (e.g., progress bars), call $output->flush().
• Validation: Caplet doesn’t validate arguments/options — check manually in your command. Fail early with $output->error('Invalid option') and return 1.
• Command Registration Timing: Register all commands before calling $caplet->run(); dynamic commands added mid-execution won’t appear in help.
• Extending Output: For colored logs, wrap the default Output\Stream with a decorator (e.g., add ANSI escape codes via helper methods in your Output subclass).
• No Built-in Tab Completion: Caplet doesn’t auto-generate completions; you’d need to maintain shell scripts separately or extend Input/Output to support such features.