Merge pull request #508 from jolicode/deprecate-suggested-values

Deprecate suggestedValues property in favor of autocomplete

CHANGELOG.md

@@ -31,6 +31,7 @@
     +    run(['composer', 'install'], context: context()->withWorkingDirectory(__DIR__));
     }
     ```
+* Deprecate `suggestedValues` property in `AsArgument` and `AsOption` attributes. Use `autocomplete` property instead.
 
 ## 0.17.1 (2024-05-31)
 

doc/going-further/interacting-with-castor/autocomplete.md

@@ -24,13 +24,13 @@ You have two options to make your arguments autocompleted.
 
 ### Static suggestions
 
-In case your suggestions are fixed, you can pass them in the `suggestedValues`
-property of the `AsArgument` and `AsOption` attributes:
+In case your suggestions are fixed, you can pass them as an array in the
+`autocomplete` property of the `AsArgument` and `AsOption` attributes:
 
 ```php
 #[AsTask()]
 function my_task(
-    #[AsArgument(name: 'argument', suggestedValues: ['foo', 'bar', 'baz'])]
+    #[AsArgument(name: 'argument', autocomplete: ['foo', 'bar', 'baz'])]
     string $argument,
 ): void {
 }
@@ -48,8 +48,9 @@ bar  baz  foo
 
 In case you need some logic to list the suggestions (like suggesting paths or
 docker services, making a database query or HTTP request to determine some
-values, etc.), you can use the `autocomplete` property of the `AsArgument` and
-`AsOption` attributes to provide the function that will return the suggestions:
+values, etc.), you can use the same `autocomplete` property of the `AsArgument`
+and `AsOption` attributes to provide the function that will return the
+suggestions:
 
 ```php
 namespace example;
@@ -91,5 +92,5 @@ argument to allow you to pre-filter the suggestions returned to the shell.
 > user. You do not have to implement any filter logic in the function.
 > 
 > You may use CompletionInput::getCompletionValue() to get the current input if
-> that helps improving performance (e.g. by reducing the number of rows fetched
+> that helps to improve performance (e.g. by reducing the number of rows fetched
 > from the database).

examples/args.php

@@ -15,7 +15,7 @@
  */
 #[AsTask(description: 'Dumps all arguments and options, with custom configuration')]
 function args(
-    #[AsArgument(description: 'This is a required argument without any typing', suggestedValues: ['hello', 'bonjour', 'hola'])]
+    #[AsArgument(description: 'This is a required argument without any typing', autocomplete: ['hello', 'bonjour', 'hola'])]
     $word,
     #[AsArgument(name: 'array-of-people', description: 'This is an optional array argument')]
     array $argument2 = ['world', 'PHP community'],

src/Attribute/AsArgument.php

@@ -8,12 +8,13 @@
 class AsArgument extends AsCommandArgument
 {
     /**
-     * @param array<string>                                  $suggestedValues
-     * @param mixed|callable(CompletionInput): array<string> $autocomplete
+     * @param array<string>                                          $suggestedValues
+     * @param array<string>|callable(CompletionInput): array<string> $autocomplete
      */
     public function __construct(
         ?string $name = null,
         public readonly string $description = '',
+        /** @deprecated since Castor 0.18, use "autocomplete" property instead */
         public readonly array $suggestedValues = [],
         public readonly mixed $autocomplete = null,
     ) {

src/Attribute/AsOption.php

@@ -8,15 +8,16 @@
 class AsOption extends AsCommandArgument
 {
     /**
-     * @param string|array<string>|null                      $shortcut
-     * @param array<string>                                  $suggestedValues
-     * @param mixed|callable(CompletionInput): array<string> $autocomplete
+     * @param string|array<string>|null                              $shortcut
+     * @param array<string>                                          $suggestedValues
+     * @param array<string>|callable(CompletionInput): array<string> $autocomplete
      */
     public function __construct(
         ?string $name = null,
         public readonly string|array|null $shortcut = null,
         public readonly ?int $mode = null,
         public readonly string $description = '',
+        /** @deprecated since Castor 0.18, use "autocomplete" property instead */
         public readonly array $suggestedValues = [],
         public readonly mixed $autocomplete = null,
     ) {

src/Console/Command/TaskCommand.php

@@ -242,6 +242,11 @@ private function getParameterName(\ReflectionParameter $parameter): string
      */
     private function getSuggestedValues(AsArgument|AsOption $attribute): array|\Closure
     {
+        if ($attribute->suggestedValues && !\in_array('_complete', $_SERVER['argv'], true)) {
+            // Only trigger deprecation when not in completion mode
+            trigger_deprecation('jolicode/castor', '0.18', \sprintf('The "suggestedValues" property of attribute "%s" is deprecated, use "autocomplete" property instead.', self::class));
+        }
+
         if ($attribute->suggestedValues && null !== $attribute->autocomplete) {
             throw new FunctionConfigurationException(\sprintf('You cannot define both "suggestedValues" and "autocomplete" option on parameter "%s".', $attribute->name), $this->taskDescriptor->function);
         }
@@ -250,6 +255,11 @@ private function getSuggestedValues(AsArgument|AsOption $attribute): array|\Clos
             return $attribute->suggestedValues;
         }
 
+        if (\is_array($attribute->autocomplete)) {
+            return $attribute->autocomplete;
+        }
+
+        // @phpstan-ignore booleanNot.alwaysFalse
         if (!\is_callable($attribute->autocomplete)) {
             throw new FunctionConfigurationException(\sprintf('The value provided in the "autocomplete" option on parameter "%s" is not callable.', $attribute->name), $this->taskDescriptor->function);
         }

tests/AutocompleteTest.php

@@ -37,15 +37,15 @@ public function testCompletion(\Closure $function, array $expectedValues, string
 
     public function provideCompletionTests(): \Generator
     {
-        yield [task_with_suggested_values(...), ['a', 'b', 'c']];
+        yield [task_with_static_autocomplete(...), ['a', 'b', 'c']];
         yield [task_with_autocomplete(...), ['d', 'e', 'f']];
         yield [task_with_autocomplete_filtered(...), ['foo', 'bar', 'baz']];
         yield [task_with_autocomplete_filtered(...), ['bar', 'baz'], 'ba'];
     }
 }
 
-function task_with_suggested_values(
-    #[AsArgument(name: 'argument', suggestedValues: ['a', 'b', 'c'])]
+function task_with_static_autocomplete(
+    #[AsArgument(name: 'argument', autocomplete: ['a', 'b', 'c'])]
     string $argument,
 ): void {
 }