README

One CLI for the whole framework. Commands are listed, not discovered; dependencies are declared, not reflected; exit codes mean something.

One dependency: psr/container, which is interface-only.

php bin/ix                       # every command, grouped
php bin/ix migrate --dry-run     # what would run, without running it
php bin/ix encode:lint           # template output that is not encoded
php bin/ix version               # every Italix library and its version

Writing a command

namespace App\Console;

use Italix\Console\{BaseCommand, Input, Output};
use Italix\Orm\DataManager;

final class PurgeTokensCommand extends BaseCommand
{
    /** Injected by the runner — protected, because BaseCommand assigns it */
    protected DataManager $dm;

    public static function name_code(): string  { return 'tokens:purge'; }
    public static function summary(): string { return 'Delete expired verification tokens.'; }

    public static function depends_on(): array
    {
        return ['dm' => DataManager::class];
    }

    public function run(Input $in, Output $out): int
    {
        $days_n = $in->int_option('older-than', 30);

        if ($in->flag('dry-run')) {
            $out->comment("Would purge tokens older than {$days_n} days.");

            return 0;
        }

        $done_n = $this->dm->execute('DELETE FROM …')->rowCount();
        $out->success("{$done_n} tokens purged.");

        return 0;
    }
}

'console.commands' => [
    \App\Console\MigrateCommand::class,
    \App\Console\PurgeTokensCommand::class,
],

Injected properties must be protected. A private property of the subclass is invisible from BaseCommand's scope. The runner says so by name rather than letting PHP's "Cannot access private property" stand as the whole explanation.

Input

Written	Read as
`--max=100`	`option('max')` → `'100'`, `int_option('max')` → `100`
`--force`	`flag('force')` → `true`, `has_option('force')` → `true`
`--no-cache`	`flag('cache')` → `false`, `has_option('cache')` → `true`
`-vqf`	three flags: `v`, `q`, `f`
`--`	stops option parsing; everything after is an argument
anything else	a positional argument, in order

flag() reads 0, false, no and off as false.

One trap worth knowing: --max with no value does not become 0. option() and int_option() fall back to the default, because a bare --max and an omitted --max diverging into a zero nobody asked for is how a worker ends up processing no jobs and reporting success. has_option() still reports it as given.

Output

$out->line('plain');           // stdout
$out->info('cyan');            // stdout
$out->success('green');        // stdout
$out->comment('dim');          // stdout
$out->warn('yellow');          // stderr
$out->error('red');            // stderr
$out->table(['a', 'b'], $rows);

Diagnostics go to stderr. A command whose errors land on stdout cannot be piped: ix jobs:status | grep failed would match its own error message.

Colour only when a terminal is watching. Escape codes are emitted when the stream is a TTY and suppressed otherwise, so a CI log gets text rather than \e[32m. NO_COLOR is honoured.

Output::in_memory() returns one that writes into memory; fetch() and fetch_errors() read it back. That is how the suite asserts on which stream a message went to.

Exit codes

Code	Meaning
0	the command succeeded
1	the command failed, or threw
2	usage error — unknown verb, bad registration, missing container

The 1/2 split is the one encode-lint already used. run() returning a code the runner passes through verbatim is the point: a command that fails with 0 is the CLI equivalent of a validation rule that never runs.

An uncaught exception prints class, message, file and line, then suggests -v for the trace.

Wiring it up

bin/ix boots the same configuration the web entry point does and takes the container from the engine:

$config = require "{$site_dir}/conf.php";
$config['base_dir'] = $base_dir;
$config['host']     = $host;

$engine = new Engine($config);

exit(console($config['console.commands'] ?? [], $engine->registry(), 'ix', 'Acme')->run($argv));

Engine::registry() builds the container without the dispatcher, so ix version does not write a route cache file as a side effect.

That shared container is the fix for a real bug: the old run_migration.php rebuilt the database credentials from $_ENV with its own defaults, so a change in conf.php never reached migrations.

Deliberately not

No auto-discovery. Commands are listed in conf.php, like routes. A command that appears because a file was copied into place is a command nobody decided to ship.
No interactive prompts, no progress bars. Both assume a human is watching; these verbs run from cron and CI as often as from a terminal.
No option schema. A command asks for what it wants with the default it wants, rather than maintaining a second description of every flag.

italix / console

Maintainers

Package info

Statistics

Security