breadcrumb-the-shire/lib/Console/Command.php

<?php

namespace MintyPHP\Console;

/**
 * Base class for CLI commands.
 *
 * Subclasses define a name (e.g. 'module:sync') and implement execute().
 * Bootstrap helpers provide a stable way to initialize the app without
 * fragile relative paths.
 */
abstract class Command
{
    abstract public function name(): string;

    abstract public function description(): string;

    /**
     * Optional usage text shown when --help is passed for this command.
     * Override in subclasses that accept arguments or options.
     */
    public function usage(): string
    {
        return '';
    }

    /**
     * @param list<string> $args Positional arguments (after the command name)
     * @param array<string, string|bool> $options Parsed --key=value and --flag options
     * @return int Exit code (0 = success)
     */
    abstract public function execute(array $args, array $options): int;

    // ─── Bootstrap helpers ──────────────────────────────────────────

    protected function projectRoot(): string
    {
        return dirname(__DIR__, 2);
    }

    /**
     * Bootstrap the app for non-module CLI commands.
     * Wraps bin/cli-bootstrap.php with stable path resolution.
     */
    protected function bootstrapApp(string $channel = 'cli', ?string $path = null): void
    {
        require_once $this->projectRoot() . '/bin/cli-bootstrap.php';

        cliBootstrapApp($channel, $path ?? 'bin/console ' . $this->name());
    }

    /**
     * Bootstrap the app for module CLI commands.
     * Loads the module CLI infrastructure (error policy, locking, app container).
     */
    protected function bootstrapModuleApp(): void
    {
        require_once $this->projectRoot() . '/bin/module-cli-bootstrap.php';

        moduleCliBootstrapApp();
    }

    /**
     * Require a bin script by name (e.g. 'module-migrate.php').
     * Resolves the path from projectRoot — no fragile relative paths.
     */
    protected function requireBinScript(string $filename): void
    {
        require_once $this->projectRoot() . '/bin/' . $filename;
    }
}