README

Waffle Console Component

Release: 0.1.0-beta3  |  CHANGELOG.md

A minimalist, zero-magic CLI runtime for the Waffle Framework (RFC-012). Commands are registered explicitly at boot — no auto-discovery — and resolve their dependencies through constructor injection.

📦 Installation

composer require waffle-commons/console

🧱 Surface

🚀 Quick start

The exact signature of ConsoleApplication::__construct, verbatim from src/ConsoleApplication.php:

public function __construct(
    private readonly string $name = Constant::DEFAULT_APP_NAME,
    private readonly string $version = '0.0.0',
    private readonly OutputInterface $output = new StreamOutput(),
    ?array $argv = null, // null → reads $_SERVER['argv']
) { /* … */ }

And the run loop:

use Waffle\Commons\Console\ConsoleApplication;
use Waffle\Commons\Console\Command\CacheClearCommand;
use Waffle\Commons\Console\Command\RouteListCommand;

$app = new ConsoleApplication(name: 'Waffle', version: '0.1.0-beta0');

$app->add(new CacheClearCommand($cache));
$app->add(new RouteListCommand($router));

exit($app->run()); // argv read from constructor, returns int exit code

🪜 Public API

final class ConsoleApplication implements ConsoleApplicationInterface
{
    public function getName(): string;
    public function getVersion(): string;
    public function add(CommandInterface $command): void;
    public function has(string $name): bool;
    public function find(string $name): CommandInterface;  // throws CommandNotFoundException
    public function all(): array;
    public function run(): int;                            // returns ExitCode::*->value
}

run():

1. With no arguments, prints the available-commands listing and exits with ExitCode::USAGE.
2. The built-in list command name reprints the same listing with ExitCode::SUCCESS.
3. -v / -vv / -vvv / --verbose / --very-verbose / --debug / --quiet flags adjust output verbosity via OutputInterface::setVerbosity(Verbosity).
4. Dispatches to the resolved command's execute(InputInterface, OutputInterface): int.
5. ConsoleExceptionInterface and any other Throwable are caught and returned as ExitCode::FAILURE, with the message printed to stderr.

🐘 PHP 8.5 features used

• final class ConsoleApplication.
• Constructor property promotion + private readonly on every dependency.
• Default OutputInterface $output = new StreamOutput() — PHP 8.1 new in initializers.
• enum ExitCode: int and enum Verbosity (from contracts) for typed exit codes / verbosity levels.
• Typed constants via Waffle\Commons\Contracts\Console\Constant.

🧭 Architectural boundary (mago guard)

An active dependency perimeter is enforced on every CI run by vendor/bin/mago guard (bundled into composer mago; zero baselines). The rules live in mago.toml under [guard.perimeter] — a forbidden use statement fails the build, not a reviewer.

Production code under Waffle\Commons\Console may depend only on:

• Waffle\Commons\Console\** — itself
• Waffle\Commons\Contracts\** — the shared contracts package, the only Waffle dependency permitted
• Psr\** — PSR interfaces
• @global + Psl\** — PHP core and the PHP Standard Library

Test code under WaffleTests\Commons\Console is unrestricted (@all). Structural rules are guarded too: interfaces must be named *Interface, Exception\** classes must end in *Exception, and any Enum\** namespace may hold only enum declarations.

Contract-first, component-agnostic by construction: components compose through waffle-commons/contracts, never directly through one another.

🧪 Testing

docker exec -w /waffle-commons/console waffle-dev composer tests

📄 License

MIT — see LICENSE.md.