Command.php

<?php
/*
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
 */
/**
 * Italix Console - Command
 *
 * @package Italix\Console
 */

declare(strict_types=1);

namespace Italix\Console;

/**
 * One verb of the framework CLI.
 *
 * The shape mirrors a controller: the class declares what it needs through a
 * static `depends_on()` map, the runner resolves those keys from the container
 * and hands them to the constructor. A command is therefore no harder to test
 * than an action — construct it with a fake, call `run()`, read the exit code.
 *
 * Names are machine codes with a namespace prefix (`jobs:work`, `lang:extract`,
 * `make:admin`), which is what lets `ix list` group them without a registry of
 * groups.
 *
 * @example
 * final class JobsWorkCommand extends BaseCommand
 * {
 *     private JobQueue $queue;
 *
 *     public static function name_code(): string { return 'jobs:work'; }
 *     public static function summary(): string { return 'Run queued jobs until the queue is empty.'; }
 *
 *     public static function depends_on(): array
 *     {
 *         return ['queue' => JobQueue::class];
 *     }
 *
 *     public function run(Input $in, Output $out): int
 *     {
 *         $done_n = $this->queue->work((int) $in->option('max', '0'));
 *         $out->line("{$done_n} jobs.");
 *
 *         return 0;
 *     }
 * }
 */
interface Command
{
    /**
     * The verb, as typed: `jobs:work`.
     */
    public static function name_code(): string;

    /**
     * One line, shown by `ix list`. No trailing period is added or removed.
     */
    public static function summary(): string;

    /**
     * Services this command needs: property name => container key.
     *
     * The same contract as `BaseController::depends_on()`, deliberately: a
     * declared list beats reflection because it can be read without running
     * anything.
     *
     * @return array<string, string>
     */
    public static function depends_on(): array;

    /**
     * Do the work and return a process exit code.
     *
     * 0 is success. Anything else is a failure the caller can act on, and a
     * command that fails silently with 0 is the CLI equivalent of a validation
     * rule that never runs.
     */
    public function run(Input $in, Output $out): int;
}