Download the PHP package celema/console without Composer

Celema Console

A command line interface helper.

Features

• Commands are plain classes marked with a #[Command] attribute — no base class, free constructors
• Arguments and options are __invoke() parameters marked #[Arg] or #[Opt], converted to their declared types — string, int, float, bool, array, or a backed enum — with defaults from the signature
• Option groups: classes bundling #[Opt] constructor parameters, shared by several commands
• Automatic help generation from the #[Command] attribute and the __invoke() signature
• Strict by default: the parameters are a command's complete interface — an unknown or malformed option (with a "Did you mean" suggestion), a value of the wrong type, a missing required argument, or an undeclared positional aborts with exit code 2 before the command runs; an array argument takes open-ended input
• Raw access to the parsed options and positionals via an injected Args object
• Lazy command construction: factories or an optional class resolver run only for the invoked command
• Anonymous classes as lightweight one-off commands — attributes work inline
• Built-in color support with per-stream terminal detection and NO_COLOR/FORCE_COLOR handling
• Command help with php run help <command> or php run <command> --help
• Built-in commands command for shell autocomplete
• --key=value options (repeatable) and boolean --flag / -h flags, negatable as --no-flag; -- ends option parsing
• Output from markup templates and data arguments: $io->error('Cannot read <strong>%s</strong>', $path) needs no escaping; line(), write(), success(), warn(), and error() (warnings and errors go to STDERR, as does everything written through $io->stderr())
• Inline markup for styled output: <strong>, <em>, <dim>, <u>, the ANSI colors — <green>, <bright-red>, <bg-blue>, ... — and truecolor hex tags: <#ff7313>, <bg-#ff7313>
• Interactive prompts: ask(), secret() for hidden input, confirm(), and choice()
• Buffer, a terminal in memory for testing commands without output buffering or escape-code stripping
• Text formatting helpers: indent() wraps, pad() aligns, rule() separates — all on the visible width, markup and multibyte aware
• Table for minimal scc-style column output — no borders, no cell wrapping
• Debug mode for detailed error traces

Installation

Quick Start

A command is a plain invokable class with a #[Command] attribute:

__invoke() must declare the return type int (the exit code). An Io parameter is injected; #[Arg] parameters take the positional arguments in order and #[Opt] parameters the options, named after the parameter in kebab-case. Options use --key=value (a flag like --force has no value), and every option needs a default.

Create a runner script and pass its exit code to exit():

Run your command:

Resolving Commands

Register class names with an optional resolver to construct commands through your container or application runtime:

The resolver receives the registered class name and must return an instance of that class or a subclass. Commands are resolved only when invoked, then cached per registration; instances and explicit factories bypass the resolver. Without a resolver, class names use a zero-argument constructor. Console has no container dependency.

Commands can also receive Io through their constructors. Configure the resolver to supply the same Io instance you pass to the runner as its output; Console does not register services in your container. See Registering Commands for details.

Mutation testing

Mutation testing with Infection is not part of composer ci, but the CI workflow runs it after the coverage step and enforces the minimum mutation score from infection.json5.dist. Pushes only mutate the changed lines; a weekly scheduled run covers the whole codebase. Run it locally with:

Reports are written to .infection/.

License

This project is licensed under the MIT license.