Add explicit support for #[Command], #[Hook], and more PHP8 Attributes

.gitignore

@@ -2,6 +2,7 @@
 phpunit.xml
 vendor
 build
+.env
 tools
 .idea
 .phpunit.result.cache

README.md

@@ -1,6 +1,6 @@
 # Consolidation\AnnotatedCommand
 
-Initialize Symfony Console commands from annotated command class methods.
+Initialize Symfony Console commands from annotated/attributed command class methods.
 
 [![ci](https://github.com/consolidation/annotated-command/workflows/CI/badge.svg)](https://travis-ci.org/consolidation/annotated-command)
 [![scrutinizer](https://scrutinizer-ci.com/g/consolidation/annotated-command/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/consolidation/annotated-command/?branch=master)
@@ -65,6 +65,24 @@ class MyCommandClass
 }
 ```
 
+or via PHP 8 attributes.
+
+```php
+    #[CLI\Name(name: 'my:echo', aliases: ['c'])]
+    #[CLI\Help(description: 'This is the my:echo command', synopsis: "This command will concatenate two parameters. If the --flip flag\nis provided, then the result is the concatenation of two and one.",)]
+    #[CLI\Param(name: 'one', description: 'The first parameter')]
+    #[CLI\Param(name: 'two', description: 'The other parameter')]
+    #[CLI\Option(name: 'flip', description: 'Whether or not the second parameter should come first in the result.')]
+    #[CLI\Usage(name: 'bet alpha --flip', description: 'Concatenate "alpha" and "bet".')]
+    public function myEcho($one, $two = '', array $options = ['flip' => false])
+    {
+        if ($options['flip']) {
+            return "{$two}{$one}";
+        }
+        return "{$one}{$two}";
+    }
+```
+
 ### Legacy Annotated Command Methods
 The legacy method for declaring commands is still supported. When using the legacy method, the command options, if any, are declared as the last parameter of the methods. The options will be passed in as an associative array; the default options of the last parameter should list the options recognized by the command.  The rest of the parameters are arguments. Parameters with a default value are optional; those without a default value are required.
 ```php
@@ -94,6 +112,7 @@ class MyCommandClass
     }
 }
 ```
+## Option Default Values
 
 The `$options` array must be an associative array whose key is the name of the option, and whose value is one of:
 

composer.json

@@ -43,7 +43,7 @@
         "cbf": "phpcbf --standard=PSR2 -n src",
         "unit": "SHELL_INTERACTIVE=true phpunit --colors=always",
         "lint": [
-            "find src -name '*.php' -print0 | xargs -0 -n1 php -l",
+            "find src -name '*.php' -and ! -path 'src/Attributes/*' -print0 | xargs -0 -n1 php -l",
             "find tests/src -name '*.php' -and ! -name 'ExampleAttributesCommandFile.php' -print0 | xargs -0 -n1 php -l"
         ],
         "test": [

phpunit.xml.dist

@@ -14,6 +14,9 @@
   <filter>
     <whitelist processUncoveredFilesFromWhitelist="true">
       <directory suffix=".php">src</directory>
+      <exclude>
+        <directory suffix=".php">src/Attributes</directory>
+      </exclude>
     </whitelist>
   </filter>
 </phpunit>

src/Attributes/Argument.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace Consolidation\AnnotatedCommand\Attributes;
+
+use Attribute;
+use Consolidation\AnnotatedCommand\Parser\CommandInfo;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
+class Argument
+{
+    /**
+     * @param $name
+     *   The name of the argument.
+     * @param $description
+     *   A one line description.
+     */
+    public function __construct(
+        public string $name,
+        public string $description
+    ) {
+    }
+
+    public static function handle(\ReflectionAttribute $attribute, CommandInfo $commandInfo)
+    {
+        $args = $attribute->getArguments();
+        $commandInfo->addArgumentDescription($args['name'], @$args['description']);
+    }
+}

src/Attributes/Command.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Consolidation\AnnotatedCommand\Attributes;
+
+use Attribute;
+use Consolidation\AnnotatedCommand\Parser\CommandInfo;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class Command
+{
+    /**
+     * @param $name
+     *  The name of the command or hook.
+     * @param string[] $aliases
+     *   An array of alternative names for this item.
+     */
+    public function __construct(
+        public string $name,
+        public array $aliases = [],
+    ) {
+    }
+
+    public static function handle(\ReflectionAttribute $attribute, CommandInfo $commandInfo)
+    {
+        $args = $attribute->getArguments();
+        $commandInfo->setName($args['name']);
+        $commandInfo->addAnnotation('command', $args['name']);
+        $commandInfo->setAliases($args['aliases'] ?? []);
+    }
+}

src/Attributes/DefaultFields.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Consolidation\AnnotatedCommand\Attributes;
+
+use Attribute;
+use Consolidation\AnnotatedCommand\Parser\CommandInfo;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class DefaultFields
+{
+    /**
+     * @param $fields
+     *   An array of field names to show by default.
+     */
+    public function __construct(
+        public array $fields,
+    ) {
+    }
+
+    public static function handle(\ReflectionAttribute $attribute, CommandInfo $commandInfo)
+    {
+        $args = $attribute->getArguments();
+        $commandInfo->addAnnotation('default-fields', $args['fields']);
+    }
+}

src/Attributes/DefaultTableFields.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Consolidation\AnnotatedCommand\Attributes;
+
+use Attribute;
+use Consolidation\AnnotatedCommand\Parser\CommandInfo;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class DefaultTableFields
+{
+    /**
+     * @param $fields
+     *   An array of field names to show by default when using table formatter.
+     */
+    public function __construct(
+        public array $fields,
+    ) {
+    }
+
+    public static function handle(\ReflectionAttribute $attribute, CommandInfo $commandInfo)
+    {
+        $args = $attribute->getArguments();
+        $commandInfo->addAnnotation('default-table-fields', $args['fields']);
+    }
+}

src/Attributes/FieldLabels.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Consolidation\AnnotatedCommand\Attributes;
+
+use Attribute;
+use Consolidation\AnnotatedCommand\Parser\CommandInfo;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class FieldLabels
+{
+    /**
+     * @param $labels
+     *   An associative array of field names and labels for display.
+     */
+    public function __construct(
+        public array $labels
+    ) {
+    }
+
+    public static function handle(\ReflectionAttribute $attribute, CommandInfo $commandInfo)
+    {
+        $args = $attribute->getArguments();
+        $commandInfo->addAnnotation('field-labels', $args['labels']);
+    }
+}

src/Attributes/FilterDefaultField.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Consolidation\AnnotatedCommand\Attributes;
+
+use Attribute;
+use Consolidation\AnnotatedCommand\Parser\CommandInfo;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class FilterDefaultField
+{
+    /**
+     * @param $field
+     *   A field name to filter on by default.
+     */
+    public function __construct(
+        public string $field
+    ) {
+    }
+
+    public static function handle(\ReflectionAttribute $attribute, CommandInfo $commandInfo)
+    {
+        $args = $attribute->getArguments();
+        $commandInfo->addAnnotation('filter-default-field', $args['field']);
+    }
+}

src/Attributes/Help.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Consolidation\AnnotatedCommand\Attributes;
+
+use Attribute;
+use Consolidation\AnnotatedCommand\Parser\CommandInfo;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class Help
+{
+    /**
+     * @param $description
+     *   A one line description.
+     * @param $synopsis
+     *   A multi-line help text.
+     * @param bool|null $hidden
+     *   Hide the command from the help list.
+     */
+    public function __construct(
+        public string $description,
+        public ?string $synopsis,
+        public bool $hidden = false
+    ) {
+    }
+
+    public static function handle(\ReflectionAttribute $attribute, CommandInfo $commandInfo)
+    {
+        $args = $attribute->getArguments();
+        $commandInfo->setDescription($args['description']);
+        $commandInfo->setHelp(@$args['synopsis']);
+        $commandInfo->setHidden(@$args['hidden']);
+    }
+}

src/Attributes/Hook.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Consolidation\AnnotatedCommand\Attributes;
+
+use Attribute;
+use Consolidation\AnnotatedCommand\Hooks\HookManager;
+use Consolidation\AnnotatedCommand\Parser\CommandInfo;
+use JetBrains\PhpStorm\ExpectedValues;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class Hook
+{
+    /**
+     * @param $type
+     *  When during the command lifecycle this hook will be called (e.g. validate).
+     * @param $target
+     *   Specifies which command(s) the hook will be attached to.
+     */
+    public function __construct(
+        #[ExpectedValues(valuesFromClass: HookManager::class)] public string $type,
+        public ?string $target
+    ) {
+    }
+
+    public static function handle(\ReflectionAttribute $attribute, CommandInfo $commandInfo)
+    {
+        $args = $attribute->getArguments();
+        $commandInfo->setName($args['target'] ?? '');
+        $commandInfo->addAnnotation('hook', $args['type'] . ' ' . $args['target'] ?? '');
+    }
+}

src/Attributes/Misc.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Consolidation\AnnotatedCommand\Attributes;
+
+use Attribute;
+use Consolidation\AnnotatedCommand\Parser\CommandInfo;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class Misc
+{
+    /**
+     * @param array $data
+     *   An associative array containing arbitrary data.
+     */
+    public function __construct(
+        public array $data,
+    ) {
+    }
+
+    public static function handle(\ReflectionAttribute $attribute, CommandInfo $commandInfo)
+    {
+        $args = $attribute->getArguments();
+        $commandInfo->AddAnnotation(key($args['data']), current($args['data']));
+    }
+}

src/Attributes/Option.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace Consolidation\AnnotatedCommand\Attributes;
+
+use Attribute;
+use Consolidation\AnnotatedCommand\Parser\CommandInfo;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
+class Option
+{
+    /**
+     * @param $name
+     *   The name of the option.
+     * @param $description
+     *   A one line description.
+     */
+    public function __construct(
+        public string $name,
+        public string $description
+    ) {
+    }
+
+    public static function handle(\ReflectionAttribute $attribute, CommandInfo $commandInfo)
+    {
+        $args = $attribute->getArguments();
+        $commandInfo->addOptionDescription($args['name'], @$args['description']);
+    }
+}

src/Attributes/Topics.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Consolidation\AnnotatedCommand\Attributes;
+
+use Attribute;
+use Consolidation\AnnotatedCommand\Parser\CommandInfo;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class Topics
+{
+    /**
+     * @param string[] $topics
+     *   An array of topics that are related to this command.
+     * @param $isTopic
+     *   This command should appear on the list of topics.
+     */
+    public function __construct(
+        public ?array $topics,
+        public bool $isTopic = false,
+    ) {
+    }
+
+    public static function handle(\ReflectionAttribute $attribute, CommandInfo $commandInfo)
+    {
+        $args = $attribute->getArguments();
+        $commandInfo->addAnnotation('topics', $args['topics'] ?? []);
+        $commandInfo->addAnnotation('topic', $args['is_topic'] ?? false);
+    }
+}