<?php declare(strict_types=1);

/**

* The file is part of inhere/console

*

* @author https://github.com/inhere

* @homepage https://github.com/inhere/php-console

* @license https://github.com/inhere/php-console/blob/master/LICENSE

*/

namespace Inhere\Console;

use Generator;

use Inhere\Console\Contract\ControllerInterface;

use Inhere\Console\Decorate\ControllerHelpTrait;

use Inhere\Console\Exception\ConsoleException;

use Inhere\Console\Handler\AbstractHandler;

use Inhere\Console\IO\Input;

use Inhere\Console\IO\Output;

use Inhere\Console\Util\Helper;

use ReflectionClass;

use ReflectionException;

use ReflectionMethod;

use ReflectionObject;

use Throwable;

use Toolkit\PFlag\FlagsParser;

use Toolkit\PFlag\FlagUtil;

use Toolkit\PFlag\SFlags;

use Toolkit\Stdlib\Obj\ObjectHelper;

use Toolkit\Stdlib\Str;

use function array_flip;

use function array_shift;

use function implode;

use function is_array;

use function is_string;

use function method_exists;

use function sprintf;

use function substr;

use function trim;

use function ucfirst;

/**

* Class Controller

*

* @package Inhere\Console

*/

abstract class Controller extends AbstractHandler implements ControllerInterface

{

use ControllerHelpTrait;

/**

* @var array global options for the group command

*/

protected static array $globalOptions = [

'--show-disabled' => 'Whether display disabled commands',

];

/**

* Action name - real subcommand name, no suffix 'Command'.

*

* eg: updateCommand() -> action: 'update'

*

* @var string

*/

private string $action = '';

/**

* The input group name.

*

* @var string

*/

private string $groupName = '';

/**

* The delimiter. eg: '/' ':'

*

* @var string

*/

private string $delimiter = ':';

/**

* @var string

*/

private string $defaultAction = '';

/**

* The action method name on the controller.

*

* @var string

*/

private string $actionMethod = '';

/**

* @var string

*/

private string $actionSuffix = self::COMMAND_SUFFIX;

/**

* Flags for all action commands

*

* ```php

* [

* action => AbstractFlags,

* action2 => AbstractFlags2,

* ]

* ```

*

* @var FlagsParser[]

* @psalm-var array<string, FlagsParser>

*/

private array $subFss = [];

/**

* @var array From disabledCommands()

*/

private array $disabledCommands = [];

/**

* TODO ...

*

* @var array

*/

private array $attachedCommands = [];

/**

* Metadata for sub-commands. such as: desc, alias

* Notice: you must add metadata on `init()`

*

* [

* 'command real name' => [

* 'desc' => 'sub command description',

* 'alias' => [],

* ],

* ],

*

* @var array

*/

protected array $commandMetas = [];

/**

* Define command alias mapping. please rewrite it on sub-class.

*

* - key is command name, value is aliases.

*

* @return array{string: list<string>}

*/

protected static function commandAliases(): array

{

// Usage:

// - method 1:

// alias => command

// [

// 'i' => 'install',

// 'ins' => 'install',

// ]

//

// - method 2:

// command => alias[]

// [

// 'install' => ['i', 'ins'],

// ]

return [];

}

protected function init(): void

{

parent::init();

// up: load sub-commands alias

$this->loadCommandAliases();

$list = $this->disabledCommands();

$this->groupName = $this->getRealGName();

// save to property

$this->disabledCommands = $list ? array_flip($list) : [];

if (!$this->actionSuffix) {

$this->actionSuffix = self::COMMAND_SUFFIX;

}

}

/**

* define disabled command list.

*

* @return array

*/

protected function disabledCommands(): array

{

// ['command1', 'command2'];

return [];

}

/**

* Will call it on subcommand not found on the group.

*

* @param string $command

* @param array $args

*

* @return bool if return True, will stop goon render group help.

*/

protected function onNotFound(string $command, array $args): bool

{

// TIP: you can add custom logic on sub-command not found.

return false;

}

/**

* @param FlagsParser $fs

*/

protected function afterInitFlagsParser(FlagsParser $fs): void

{

$fs->addOptsByRules(GlobalOption::getGroupOptions());

}

/**

* Run an action with args

*

* Usage:

*

* ```php

* $args = $this->flags->getRawArgs();

* // add option

* $args[] = '--push';

* $this->runActionWithArgs('subcmd', $args);

* ```

*

* @param string $cmd

* @param array $args

*

* @return bool|int|mixed

* @throws Throwable

*/

public function runActionWithArgs(string $cmd, array $args): mixed

{

$args[0] = $cmd;

return $this->doRun($args);

}

protected function beforeRun(): void

{

}

/**

* @param array $args

*

* @return mixed

* @throws Throwable

*/

public function doRun(array $args): mixed

{

$name = self::getName();

if (!$args) {

$command = $this->defaultAction;

// and not default command

if (!$command) {

$this->debugf('cmd: %s - run args is empty, display help for the group', $name);

return $this->showHelp();

}

} else {

$first = $args[0];

if (!FlagUtil::isValidName($first)) {

$this->debugf('cmd: %s - not input subcommand, display help for the group', $name);

return $this->showHelp();

}

$command = $first;

array_shift($args);

}

// update subcommand

$this->commandName = $command;

// update some comment vars

$fullCmd = $this->input->buildFullCmd($name, $command);

$this->setCommentsVar('fullCmd', $fullCmd);

$this->setCommentsVar('fullCommand', $fullCmd);

$this->setCommentsVar('binWithCmd', $this->input->buildCmdPath($name, $command));

// get real sub-command name

$command = $this->resolveAlias($command);

// update the command id.

$this->input->setCommandId("$name:$command");

// convert 'boo-foo' to 'booFoo'

$this->action = $action = Str::camelCase($command);

$this->debugf("cmd: %s - will run the subcommand: %s(action: %s)", $name, $command, $action);

$method = $this->getMethodName($action);

// fire event

$this->fire(ConsoleEvent::COMMAND_RUN_BEFORE, $this);

$this->beforeRun();

// check method not exist

if (!method_exists($this, $method)) {

if ($this->isSub($command)) {

return $this->dispatchSub($command, $args);

}

// if command not exists.

return $this->handleNotFound($name, $command, $args);

}

// init flags for subcommand

$fs = $this->newActionFlags();

$this->actionMethod = $method;

$this->input->setFs($fs);

$this->debugf('load flags by configure method, subcommand: %s', $command);

$this->configure();

// not config flags. load rules from method doc-comments

if ($fs->isEmpty()) {

$this->loadRulesByDocblock($method, $fs);

}

$this->log(Console::VERB_DEBUG, "run subcommand '$name.$command' - parse options", ['args' => $args]);

// parse subcommand flags.

if (!$fs->parse($args)) {

return 0;

}

// do running

return parent::doRun($args);

}

/**

* Load command configure

*/

protected function configure(): void

{

// eg. use `indexConfigure()` for `indexCommand()`

$method = $this->action . self::CONFIGURE_SUFFIX;

if (method_exists($this, $method)) {

$this->$method($this->input);

}

}

/**

* Before controller method execute

*

* @return boolean It MUST return TRUE to continue execute. if return False, will stop run.

*/

protected function beforeAction(): bool

{

return true;

}

/**

* After controller method execute

*/

protected function afterAction(): void

{

}

/**

* Run command action in the group

*

* @param Input $input

* @param Output $output

*

* @return mixed

* @throws ReflectionException

*/

final public function execute(Input $input, Output $output): mixed

{

$action = $this->action;

$group = static::getName();

if ($this->isDisabled($action)) {

$this->debugf('command %s is disabled on the group %s', $action, $group);

$output->error(sprintf("Sorry, The command '%s' is invalid in the group '%s'!", $action, $group));

return -1;

}

$method = $this->getMethodName($action);

// trigger event

$this->fire(ConsoleEvent::SUBCOMMAND_RUN_BEFORE, $this);

// the action method exists and only allow access public method.

// if (method_exists($this, $method)) {

// before run action

if (!$this->beforeAction()) {

$this->debugf('beforeAction() returns FALSE, interrupt processing continues');

return 0;

}

if (method_exists($this, $beforeFunc = 'before' . ucfirst($action))) {

$beforeOk = $this->$beforeFunc($input, $output);

if ($beforeOk === false) {

$this->debugf('%s() returns FALSE, interrupt processing continues', $beforeFunc);

return 0;

}

}

// current action flags

$flags = $this->actionFlags($action);

$rftMethod = new ReflectionMethod($this, $method);

$callArgs = ObjectHelper::buildReflectCallArgs($rftMethod, [

Input::class => $this->input,

Output::class => $this->output,

FlagsParser::class => $flags,

// 'args' => $args,

]);

// call action method

$result = $rftMethod->invokeArgs($this, $callArgs);

// call action method

// $result = $this->$method($input, $output, $flags);

// after run action

if (method_exists($this, $after = 'after' . ucfirst($action))) {

$this->$after($input, $output);

}

$this->afterAction();

return $result;

}

/**

* @param string $group

* @param string $command

* @param array $args

*

* @return int

*/

protected function handleNotFound(string $group, string $command, array $args): int

{

// if user custom handle not found logic.

if ($this->onNotFound($command, $args)) {

$this->debugf('group: %s - user custom handle the subcommand "%s" not found', $group, $command);

return 0;

}

$this->debugf('group: %s - command "%s" is not found on the group', $group, $command);

// if you defined the method '$this->notFoundCallback' , will call it

// if (($notFoundCallback = $this->notFoundCallback) && method_exists($this, $notFoundCallback)) {

// $result = $this->{$notFoundCallback}($action);

// } else {

$this->output->liteError("Sorry, The command '$command' not exist of the group '$group'!");

// find similar command names

$similar = Helper::findSimilar($command, $this->getAllCommandMethods(null, true));

if ($similar) {

$this->output->writef("\nMaybe what you mean is:\n <info>%s</info>", implode(', ', $similar));

} else {

$this->showCommandList();

}

return -1;

}

/**

* @param string $action

*

* @return FlagsParser

*/

protected function newActionFlags(string $action = ''): FlagsParser

{

$action = $action ?: $this->action;

if (!$fs = $this->getActionFlags($action)) {

$fs = new SFlags(['name' => $action]);

$fs->setStopOnFistArg(false);

$fs->setBeforePrintHelp(function (string $text) {

return $this->parseCommentsVars($text);

});

$fs->setHelpRenderer(function (): void {

$this->logf(Console::VERB_DEBUG, 'show subcommand help by input flags: -h, --help');

$this->showHelp();

});

// old mode: options and arguments at method annotations

// if ($this->compatible) {

// $fs->setSkipOnUndefined(true);

// }

// save

$this->subFss[$action] = $fs;

}

return $fs;

}

/**

* @param string $action

*

* @return string

*/

protected function getMethodName(string $action): string

{

return $this->actionSuffix ? $action . ucfirst($this->actionSuffix) : $action;

}

/**

* @return bool

*/

protected function showHelp(): bool

{

return $this->helpCommand() === 0;

}

/**

* @param array $help

*/

protected function beforeRenderCommandHelp(array &$help): void

{

$help['Group Options:'] = FlagUtil::alignOptions($this->flags->getOptsHelpLines());

}

/**

* @param ReflectionClass|null $ref

* @param bool $onlyName

*

* @return ?Generator

*/

protected function getAllCommandMethods(?ReflectionClass $ref = null, bool $onlyName = false): ?Generator

{

$ref = $ref ?: new ReflectionObject($this);

$suffix = $this->actionSuffix;

$suffixLen = Str::len($suffix);

foreach ($ref->getMethods() as $m) {

$mName = $m->getName();

if ($m->isPublic() && substr($mName, -$suffixLen) === $suffix) {

// suffix is empty ?

$cmd = $suffix ? substr($mName, 0, -$suffixLen) : $mName;

if ($onlyName) {

yield $cmd;

} else {

yield $cmd => $m;

}

}

}

}

/**

* @param string $name

*

* @return bool

*/

public function isDisabled(string $name): bool

{

return isset($this->disabledCommands[$name]);

}

/**

* load sub-commands aliases from sub-class::commandAliases()

*/

public function loadCommandAliases(): void

{

$cmdAliases = static::commandAliases();

if (!$cmdAliases) {

return;

}

foreach ($cmdAliases as $name => $item) {

// $name is command, $item is alias list

// eg: ['command1' => ['alias1', 'alias2']]

if (is_array($item)) {

$this->setAlias($name, $item, true);

} elseif (is_string($item)) { // $item is command, $name is alias name

$this->setAlias($item, $name, true);

}

}

}

/**************************************************************************

* getter/setter methods

**************************************************************************/

/**

* @return array

*/

public function getDisabledCommands(): array

{

return $this->disabledCommands;

}

/**

* @return string

*/

public function getGroupName(): string

{

return $this->groupName;

}

/**

* @return string

*/

public function getRealGName(): string

{

return self::getName();

}

/**

* @param string $groupName

*/

public function setGroupName(string $groupName): void

{

$this->groupName = $groupName;

}

/**

* @return string

*/

public function getRealCName(): string

{

return $this->action;

}

/**

* @return string

*/

public function getSubName(): string

{

return $this->commandName;

}

/**

* @param bool $useReal

*

* @return string

*/

public function getCommandId(bool $useReal = true): string

{

if ($useReal) {

return self::getName() . $this->delimiter . $this->action;

}

return $this->groupName . $this->delimiter . $this->commandName;

}

/**

* @return string

*/

public function getAction(): string

{

return $this->action;

}

/**

* @param string $action

*

* @return $this

*/

public function setAction(string $action): self

{

if ($action) {

$this->action = Str::camelCase($action);

}

return $this;

}

/**

* @return string

*/

public function getDefaultAction(): string

{

return $this->defaultAction;

}

/**

* @param string $action

*/

public function setDefaultAction(string $action): void

{

$this->defaultAction = trim($action, $this->delimiter);

}

/**

* @return string

*/

public function getActionSuffix(): string

{

return $this->actionSuffix;

}

/**

* @param string $actionSuffix

*/

public function setActionSuffix(string $actionSuffix): void

{

$this->actionSuffix = $actionSuffix;

}

/**

* @return string

*/

public function getDelimiter(): string

{

return $this->delimiter;

}

/**

* @param string $delimiter

*/

public function setDelimiter(string $delimiter): void

{

$this->delimiter = $delimiter;

}

/**

* @return array

*/

public function getCommandMetas(): array

{

return $this->commandMetas;

}

/**

* @param string $command

* @param array $meta eg: ['desc' => '', 'alias' => []]

*/

public function setCommandMeta(string $command, array $meta): void

{

if ($command) {

$this->commandMetas[$command] = $meta;

}

}

/**

* @param string $key

* @param null $default

* @param string $command if not set, will use $this->action

*

* @return mixed|null

*/

public function getCommandMeta(string $key, $default = null, string $command = ''): mixed

{

$action = $command ?: $this->action;

return $this->commandMetas[$action][$key] ?? $default;

}

/**

* @param string $action

*

* @return FlagsParser|null

*/

public function getActionFlags(string $action): ?FlagsParser

{

$action = $action ?: $this->action;

return $this->subFss[$action] ?? null;

}

/**

* @return FlagsParser

*/

public function curActionFlags(): FlagsParser

{

return $this->actionFlags($this->action);

}

/**

* @param string $action

*

* @return FlagsParser

*/

public function actionFlags(string $action): FlagsParser

{

$action = $action ?: $this->action;

if (!isset($this->subFss[$action])) {

throw new ConsoleException("not found flags parser for the action: $action");

}

return $this->subFss[$action];

}

}