diff --git a/Application.php b/Application.php index 759d5a171..7f4855b53 100644 --- a/Application.php +++ b/Application.php @@ -65,7 +65,7 @@ * Usage: * * $app = new Application('myapp', '1.0 (stable)'); - * $app->add(new SimpleCommand()); + * $app->addCommand(new SimpleCommand()); * $app->run(); * * @author Fabien Potencier @@ -389,10 +389,7 @@ public function getDefinition(): InputDefinition $this->definition ??= $this->getDefaultInputDefinition(); if ($this->singleCommand) { - $inputDefinition = $this->definition; - $inputDefinition->setArguments(); - - return $inputDefinition; + $this->definition->setArguments(); } return $this->definition; @@ -527,7 +524,7 @@ public function getLongVersion(): string */ public function register(string $name): Command { - return $this->add(new Command($name)); + return $this->addCommand(new Command($name)); } /** @@ -535,12 +532,12 @@ public function register(string $name): Command * * If a Command is not enabled it will not be added. * - * @param Command[] $commands An array of commands + * @param callable[]|Command[] $commands An array of commands */ public function addCommands(array $commands): void { foreach ($commands as $command) { - $this->add($command); + $this->addCommand($command); } } @@ -550,10 +547,14 @@ public function addCommands(array $commands): void * If a command with the same name already exists, it will be overridden. * If the command is not enabled it will not be added. */ - public function add(Command $command): ?Command + public function addCommand(callable|Command $command): ?Command { $this->init(); + if (!$command instanceof Command) { + $command = new Command(null, $command); + } + $command->setApplication($this); if (!$command->isEnabled()) { @@ -619,7 +620,7 @@ public function has(string $name): bool { $this->init(); - return isset($this->commands[$name]) || ($this->commandLoader?->has($name) && $this->add($this->commandLoader->get($name))); + return isset($this->commands[$name]) || ($this->commandLoader?->has($name) && $this->addCommand($this->commandLoader->get($name))); } /** @@ -1317,7 +1318,7 @@ private function init(): void $this->initialized = true; foreach ($this->getDefaultCommands() as $command) { - $this->add($command); + $this->addCommand($command); } } } diff --git a/Attribute/Argument.php b/Attribute/Argument.php index e6a94d2f1..bca9a2e13 100644 --- a/Attribute/Argument.php +++ b/Attribute/Argument.php @@ -11,14 +11,16 @@ namespace Symfony\Component\Console\Attribute; +use Symfony\Component\Console\Attribute\Reflection\ReflectionMember; use Symfony\Component\Console\Completion\CompletionInput; use Symfony\Component\Console\Completion\Suggestion; +use Symfony\Component\Console\Exception\InvalidArgumentException; use Symfony\Component\Console\Exception\LogicException; use Symfony\Component\Console\Input\InputArgument; use Symfony\Component\Console\Input\InputInterface; use Symfony\Component\String\UnicodeString; -#[\Attribute(\Attribute::TARGET_PARAMETER)] +#[\Attribute(\Attribute::TARGET_PARAMETER | \Attribute::TARGET_PROPERTY)] class Argument { private const ALLOWED_TYPES = ['string', 'bool', 'int', 'float', 'array']; @@ -26,7 +28,11 @@ class Argument private string|bool|int|float|array|null $default = null; private array|\Closure $suggestedValues; private ?int $mode = null; - private string $function = ''; + /** + * @var string|class-string<\BackedEnum> + */ + private string $typeName = ''; + private ?InteractiveAttributeInterface $interactiveAttribute = null; /** * Represents a console command definition. @@ -46,47 +52,54 @@ public function __construct( /** * @internal */ - public static function tryFrom(\ReflectionParameter $parameter): ?self + public static function tryFrom(\ReflectionParameter|\ReflectionProperty $member): ?self { - /** @var self $self */ - if (null === $self = ($parameter->getAttributes(self::class, \ReflectionAttribute::IS_INSTANCEOF)[0] ?? null)?->newInstance()) { - return null; - } + $reflection = new ReflectionMember($member); - if (($function = $parameter->getDeclaringFunction()) instanceof \ReflectionMethod) { - $self->function = $function->class.'::'.$function->name; - } else { - $self->function = $function->name; + if (!$self = $reflection->getAttribute(self::class)) { + return null; } - $type = $parameter->getType(); - $name = $parameter->getName(); + $type = $reflection->getType(); + $name = $reflection->getName(); if (!$type instanceof \ReflectionNamedType) { - throw new LogicException(\sprintf('The parameter "$%s" of "%s()" must have a named type. Untyped, Union or Intersection types are not supported for command arguments.', $name, $self->function)); + throw new LogicException(\sprintf('The %s "$%s" of "%s" must have a named type. Untyped, Union or Intersection types are not supported for command arguments.', $reflection->getMemberName(), $name, $reflection->getSourceName())); } - $parameterTypeName = $type->getName(); + $self->typeName = $type->getName(); + $isBackedEnum = is_subclass_of($self->typeName, \BackedEnum::class); - if (!\in_array($parameterTypeName, self::ALLOWED_TYPES, true)) { - throw new LogicException(\sprintf('The type "%s" on parameter "$%s" of "%s()" is not supported as a command argument. Only "%s" types are allowed.', $parameterTypeName, $name, $self->function, implode('", "', self::ALLOWED_TYPES))); + if (!\in_array($self->typeName, self::ALLOWED_TYPES, true) && !$isBackedEnum) { + throw new LogicException(\sprintf('The type "%s" on %s "$%s" of "%s" is not supported as a command argument. Only "%s" types and backed enums are allowed.', $self->typeName, $reflection->getMemberName(), $name, $reflection->getSourceName(), implode('", "', self::ALLOWED_TYPES))); } if (!$self->name) { $self->name = (new UnicodeString($name))->kebab(); } - $self->default = $parameter->isDefaultValueAvailable() ? $parameter->getDefaultValue() : null; + $self->default = $reflection->hasDefaultValue() ? $reflection->getDefaultValue() : null; - $self->mode = $parameter->isDefaultValueAvailable() || $parameter->allowsNull() ? InputArgument::OPTIONAL : InputArgument::REQUIRED; - if ('array' === $parameterTypeName) { + $isOptional = $reflection->hasDefaultValue() || $reflection->isNullable(); + $self->mode = $isOptional ? InputArgument::OPTIONAL : InputArgument::REQUIRED; + if ('array' === $self->typeName) { $self->mode |= InputArgument::IS_ARRAY; } - if (\is_array($self->suggestedValues) && !\is_callable($self->suggestedValues) && 2 === \count($self->suggestedValues) && ($instance = $parameter->getDeclaringFunction()->getClosureThis()) && $instance::class === $self->suggestedValues[0] && \is_callable([$instance, $self->suggestedValues[1]])) { + if (\is_array($self->suggestedValues) && !\is_callable($self->suggestedValues) && 2 === \count($self->suggestedValues) && ($instance = $reflection->getSourceThis()) && $instance::class === $self->suggestedValues[0] && \is_callable([$instance, $self->suggestedValues[1]])) { $self->suggestedValues = [$instance, $self->suggestedValues[1]]; } + if ($isBackedEnum && !$self->suggestedValues) { + $self->suggestedValues = array_column($self->typeName::cases(), 'value'); + } + + $self->interactiveAttribute = Ask::tryFrom($member, $self->name); + + if ($self->interactiveAttribute && $isOptional) { + throw new LogicException(\sprintf('The %s "$%s" argument of "%s" cannot be both interactive and optional.', $reflection->getMemberName(), $self->name, $reflection->getSourceName())); + } + return $self; } @@ -105,6 +118,28 @@ public function toInputArgument(): InputArgument */ public function resolveValue(InputInterface $input): mixed { - return $input->getArgument($this->name); + $value = $input->getArgument($this->name); + + if (is_subclass_of($this->typeName, \BackedEnum::class) && (\is_string($value) || \is_int($value))) { + return $this->typeName::tryFrom($value) ?? throw InvalidArgumentException::fromEnumValue($this->name, $value, $this->suggestedValues); + } + + return $value; + } + + /** + * @internal + */ + public function getInteractiveAttribute(): ?InteractiveAttributeInterface + { + return $this->interactiveAttribute; + } + + /** + * @internal + */ + public function isRequired(): bool + { + return InputArgument::REQUIRED === (InputArgument::REQUIRED & $this->mode); } } diff --git a/Attribute/AsCommand.php b/Attribute/AsCommand.php index 767d46ebb..8b4cea9c8 100644 --- a/Attribute/AsCommand.php +++ b/Attribute/AsCommand.php @@ -13,11 +13,9 @@ /** * Service tag to autoconfigure commands. - * - * @final since Symfony 7.3 */ #[\Attribute(\Attribute::TARGET_CLASS)] -class AsCommand +final class AsCommand { /** * @param string $name The name of the command, used when calling it (i.e. "cache:clear") @@ -25,6 +23,7 @@ class AsCommand * @param string[] $aliases The list of aliases of the command. The command will be executed when using one of them (i.e. "cache:clean") * @param bool $hidden If true, the command won't be shown when listing all the available commands, but it can still be run as any other command * @param string|null $help The help content of the command, displayed with the help page + * @param string[] $usages The list of usage examples, displayed with the help page */ public function __construct( public string $name, @@ -32,6 +31,7 @@ public function __construct( array $aliases = [], bool $hidden = false, public ?string $help = null, + public array $usages = [], ) { if (!$hidden && !$aliases) { return; diff --git a/Attribute/Ask.php b/Attribute/Ask.php new file mode 100644 index 000000000..5961953ae --- /dev/null +++ b/Attribute/Ask.php @@ -0,0 +1,147 @@ + + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace Symfony\Component\Console\Attribute; + +use Symfony\Component\Console\Attribute\Reflection\ReflectionMember; +use Symfony\Component\Console\Exception\InvalidArgumentException; +use Symfony\Component\Console\Exception\LogicException; +use Symfony\Component\Console\Input\InputInterface; +use Symfony\Component\Console\Question\ConfirmationQuestion; +use Symfony\Component\Console\Question\Question; +use Symfony\Component\Console\Style\SymfonyStyle; + +#[\Attribute(\Attribute::TARGET_PARAMETER | \Attribute::TARGET_PROPERTY)] +class Ask implements InteractiveAttributeInterface +{ + public ?\Closure $normalizer; + public ?\Closure $validator; + private \Closure $closure; + + /** + * @param string $question The question to ask the user + * @param string|bool|int|float|null $default The default answer to return if the user enters nothing + * @param bool $hidden Whether the user response must be hidden or not + * @param bool $multiline Whether the user response should accept newline characters + * @param bool $trimmable Whether the user response must be trimmed or not + * @param int|null $timeout The maximum time the user has to answer the question in seconds + * @param callable|null $validator The validator for the question + * @param int|null $maxAttempts The maximum number of attempts allowed to answer the question. + * Null means an unlimited number of attempts + */ + public function __construct( + public string $question, + public string|bool|int|float|null $default = null, + public bool $hidden = false, + public bool $multiline = false, + public bool $trimmable = true, + public ?int $timeout = null, + ?callable $normalizer = null, + ?callable $validator = null, + public ?int $maxAttempts = null, + ) { + $this->normalizer = $normalizer ? $normalizer(...) : null; + $this->validator = $validator ? $validator(...) : null; + } + + /** + * @internal + */ + public static function tryFrom(\ReflectionParameter|\ReflectionProperty $member, string $name): ?self + { + $reflection = new ReflectionMember($member); + + if (!$self = $reflection->getAttribute(self::class)) { + return null; + } + + $type = $reflection->getType(); + + if (!$type instanceof \ReflectionNamedType) { + throw new LogicException(\sprintf('The %s "$%s" of "%s" must have a named type. Untyped, Union or Intersection types are not supported for interactive questions.', $reflection->getMemberName(), $name, $reflection->getSourceName())); + } + + $self->closure = function (SymfonyStyle $io, InputInterface $input) use ($self, $reflection, $name, $type) { + if ($reflection->isProperty() && isset($this->{$reflection->getName()})) { + return; + } + + if ($reflection->isParameter() && !\in_array($input->getArgument($name), [null, []], true)) { + return; + } + + if ('bool' === $type->getName()) { + $self->default ??= false; + + if (!\is_bool($self->default)) { + throw new LogicException(\sprintf('The "%s::$default" value for the %s "$%s" of "%s" must be a boolean.', self::class, $reflection->getMemberName(), $name, $reflection->getSourceName())); + } + + $question = new ConfirmationQuestion($self->question, $self->default); + } else { + $question = new Question($self->question, $self->default); + } + $question->setHidden($self->hidden); + $question->setMultiline($self->multiline); + $question->setTrimmable($self->trimmable); + $question->setTimeout($self->timeout); + + if (!$self->validator && $reflection->isProperty() && 'array' !== $type->getName()) { + $self->validator = function (mixed $value) use ($reflection): mixed { + return $this->{$reflection->getName()} = $value; + }; + } + + $question->setValidator($self->validator); + $question->setMaxAttempts($self->maxAttempts); + + if ($self->normalizer) { + $question->setNormalizer($self->normalizer); + } elseif (is_subclass_of($type->getName(), \BackedEnum::class)) { + /** @var class-string<\BackedEnum> $backedType */ + $backedType = $reflection->getType()->getName(); + $question->setNormalizer(fn (string|int $value) => $backedType::tryFrom($value) ?? throw InvalidArgumentException::fromEnumValue($reflection->getName(), $value, array_column($backedType::cases(), 'value'))); + } + + if ('array' === $type->getName()) { + $value = []; + while ($v = $io->askQuestion($question)) { + if ("\x4" === $v || \PHP_EOL === $v || ($question->isTrimmable() && '' === $v = trim($v))) { + break; + } + $value[] = $v; + } + } else { + $value = $io->askQuestion($question); + } + + if (null === $value && !$reflection->isNullable()) { + return; + } + + if ($reflection->isProperty()) { + $this->{$reflection->getName()} = $value; + } else { + $input->setArgument($name, $value); + } + }; + + return $self; + } + + /** + * @internal + */ + public function getFunction(object $instance): \ReflectionFunction + { + return new \ReflectionFunction($this->closure->bindTo($instance, $instance::class)); + } +} diff --git a/Attribute/Interact.php b/Attribute/Interact.php new file mode 100644 index 000000000..188071ff1 --- /dev/null +++ b/Attribute/Interact.php @@ -0,0 +1,51 @@ + + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace Symfony\Component\Console\Attribute; + +use Symfony\Component\Console\Exception\LogicException; + +#[\Attribute(\Attribute::TARGET_METHOD)] +class Interact implements InteractiveAttributeInterface +{ + private \ReflectionMethod $method; + + /** + * @internal + */ + public static function tryFrom(\ReflectionMethod $method): ?self + { + /** @var self|null $self */ + if (!$self = ($method->getAttributes(self::class)[0] ?? null)?->newInstance()) { + return null; + } + + if (!$method->isPublic() || $method->isStatic()) { + throw new LogicException(\sprintf('The interactive method "%s::%s()" must be public and non-static.', $method->getDeclaringClass()->getName(), $method->getName())); + } + + if ('__invoke' === $method->getName()) { + throw new LogicException(\sprintf('The "%s::__invoke()" method cannot be used as an interactive method.', $method->getDeclaringClass()->getName())); + } + + $self->method = $method; + + return $self; + } + + /** + * @internal + */ + public function getFunction(object $instance): \ReflectionFunction + { + return new \ReflectionFunction($this->method->getClosure($instance)); + } +} diff --git a/Attribute/InteractiveAttributeInterface.php b/Attribute/InteractiveAttributeInterface.php new file mode 100644 index 000000000..0b02d7d25 --- /dev/null +++ b/Attribute/InteractiveAttributeInterface.php @@ -0,0 +1,20 @@ + + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace Symfony\Component\Console\Attribute; + +/** + * @internal + */ +interface InteractiveAttributeInterface +{ + public function getFunction(object $instance): \ReflectionFunction; +} diff --git a/Attribute/MapInput.php b/Attribute/MapInput.php new file mode 100644 index 000000000..0b508361a --- /dev/null +++ b/Attribute/MapInput.php @@ -0,0 +1,188 @@ + + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace Symfony\Component\Console\Attribute; + +use Symfony\Component\Console\Attribute\Reflection\ReflectionMember; +use Symfony\Component\Console\Exception\LogicException; +use Symfony\Component\Console\Input\InputInterface; +use Symfony\Component\Console\Interaction\Interaction; + +/** + * Maps a command input into an object (DTO). + */ +#[\Attribute(\Attribute::TARGET_PARAMETER | \Attribute::TARGET_PROPERTY)] +final class MapInput +{ + /** + * @var array + */ + private array $definition = []; + + private \ReflectionClass $class; + + /** + * @var list + */ + private array $interactiveAttributes = []; + + /** + * @internal + */ + public static function tryFrom(\ReflectionParameter|\ReflectionProperty $member): ?self + { + $reflection = new ReflectionMember($member); + + if (!$self = $reflection->getAttribute(self::class)) { + return null; + } + + $type = $reflection->getType(); + + if (!$type instanceof \ReflectionNamedType) { + throw new LogicException(\sprintf('The input %s "%s" must have a named type.', $reflection->getMemberName(), $member->name)); + } + + if (!class_exists($class = $type->getName())) { + throw new LogicException(\sprintf('The input class "%s" does not exist.', $type->getName())); + } + + $self->class = new \ReflectionClass($class); + + foreach ($self->class->getProperties() as $property) { + if ($argument = Argument::tryFrom($property)) { + $self->definition[$property->name] = $argument; + } elseif ($option = Option::tryFrom($property)) { + $self->definition[$property->name] = $option; + } elseif ($input = self::tryFrom($property)) { + $self->definition[$property->name] = $input; + } + + if (isset($self->definition[$property->name]) && (!$property->isPublic() || $property->isStatic())) { + throw new LogicException(\sprintf('The input property "%s::$%s" must be public and non-static.', $self->class->name, $property->name)); + } + } + + if (!$self->definition) { + throw new LogicException(\sprintf('The input class "%s" must have at least one argument or option.', $self->class->name)); + } + + foreach ($self->class->getMethods() as $method) { + if ($attribute = Interact::tryFrom($method)) { + $self->interactiveAttributes[] = $attribute; + } + } + + return $self; + } + + /** + * @internal + */ + public function resolveValue(InputInterface $input): object + { + $instance = $this->class->newInstanceWithoutConstructor(); + + foreach ($this->definition as $name => $spec) { + // ignore required arguments that are not set yet (may happen in interactive mode) + if ($spec instanceof Argument && $spec->isRequired() && \in_array($input->getArgument($spec->name), [null, []], true)) { + continue; + } + + $instance->$name = $spec->resolveValue($input); + } + + return $instance; + } + + /** + * @internal + */ + public function setValue(InputInterface $input, object $object): void + { + foreach ($this->definition as $name => $spec) { + $property = $this->class->getProperty($name); + + if (!$property->isInitialized($object) || \in_array($value = $property->getValue($object), [null, []], true)) { + continue; + } + + match (true) { + $spec instanceof Argument => $input->setArgument($spec->name, $value), + $spec instanceof Option => $input->setOption($spec->name, $value), + $spec instanceof self => $spec->setValue($input, $value), + default => throw new LogicException('Unexpected specification type.'), + }; + } + } + + /** + * @return iterable + */ + public function getArguments(): iterable + { + foreach ($this->definition as $spec) { + if ($spec instanceof Argument) { + yield $spec; + } elseif ($spec instanceof self) { + yield from $spec->getArguments(); + } + } + } + + /** + * @return iterable