refactor(rectors): Rename HasOptionsDocCommentRector to HasOptionsRector and improve options

guanguans · guanguans · commit b030b0e48028 · 2025-11-14T21:26:20.000+08:00
- Rename class/file and update registries to use HasOptionsRector
- Add options doc generation and list-type method/property stubs for array options
- Add imports (Collection, Pluralizer, PropertyBuilder, SimplePhpParser) and update type mapping to treat '[]' suffix as array

Signed-off-by: guanguans &lt;ityaozm@gmail.com&gt;
diff --git a/baselines/loader.neon b/baselines/loader.neon
@@ -1,8 +1,9 @@
-# total 15 errors
+# total 16 errors
 
 includes:
     - assign.propertyType.neon
     - disallowed.function.neon
     - function.alreadyNarrowedType.neon
+    - method.nonObject.neon
     - new.static.neon
     - typePerfect.narrowPublicClassMethodParamType.neon
diff --git a/baselines/method.nonObject.neon b/baselines/method.nonObject.neon
@@ -0,0 +1,8 @@
+# total 1 error
+
+parameters:
+    ignoreErrors:
+        -
+            message: '#^Cannot call method whenNotEmpty\(\) on Illuminate\\Support\\Collection\<int, string\>\|null\.$#'
+            count: 1
+            path: ../src/Foundation/Rectors/HasOptionsRector.php
diff --git a/composer.json b/composer.json
@@ -95,6 +95,7 @@
         "illuminate/support": "^9.52 || ^10.0 || ^11.0 || ^12.0",
         "infection/extension-installer": "^0.1",
         "infection/infection": "^0.26",
+        "kevinrob/guzzle-cache-middleware": "^5.1 || ^6.0 || ^7.0",
         "mockery/mockery": "^1.6",
         "nette/utils": "^4.0",
         "pestphp/pest": "^1.23 || ^2.0 || ^3.0 || ^4.0",
diff --git a/rector-php82.php b/rector-php82.php
@@ -14,7 +14,7 @@
  */
 
 use Guanguans\Notify\Foundation\Rectors\HasHttpClientDocCommentRector;
-use Guanguans\Notify\Foundation\Rectors\HasOptionsDocCommentRector;
+use Guanguans\Notify\Foundation\Rectors\HasOptionsRector;
 use Guanguans\Notify\Foundation\Rectors\ToInternalExceptionRector;
 use Rector\Config\RectorConfig;
 use Rector\Php82\Rector\Param\AddSensitiveParameterAttributeRector;
@@ -33,7 +33,7 @@
     ->withPhpVersion(PhpVersion::PHP_82)
     ->withRules([
         HasHttpClientDocCommentRector::class,
-        HasOptionsDocCommentRector::class,
+        HasOptionsRector::class,
         ToInternalExceptionRector::class,
     ])
     ->withConfiguredRule(AddSensitiveParameterAttributeRector::class, [
diff --git a/rector.php b/rector.php
@@ -21,7 +21,7 @@
 use Guanguans\Notify\Foundation\Concerns\HasOptions;
 use Guanguans\Notify\Foundation\Method;
 use Guanguans\Notify\Foundation\Rectors\HasHttpClientDocCommentRector;
-use Guanguans\Notify\Foundation\Rectors\HasOptionsDocCommentRector;
+use Guanguans\Notify\Foundation\Rectors\HasOptionsRector;
 use Guanguans\Notify\Foundation\Rectors\ToInternalExceptionRector;
 use Guanguans\Notify\Foundation\Response;
 use GuzzleHttp\RequestOptions;
@@ -113,7 +113,7 @@
         StaticClosureRector::class,
         SortAssociativeArrayByKeyRector::class,
         HasHttpClientDocCommentRector::class,
-        HasOptionsDocCommentRector::class,
+        HasOptionsRector::class,
         ToInternalExceptionRector::class,
     ])
     ->withConfiguredRule(ChangeMethodVisibilityRector::class, [
diff --git a/src/Foundation/Rectors/HasOptionsRector.php b/src/Foundation/Rectors/HasOptionsRector.php
@@ -18,15 +18,23 @@
 use Guanguans\Notify\Foundation\Message;
 use Guanguans\Notify\Foundation\Support\Str;
 use Guanguans\Notify\Foundation\Support\Utils;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Pluralizer;
+use PhpParser\Builder\Property as PropertyBuilder;
 use PhpParser\Node;
+use PhpParser\Node\ArrayItem;
+use PhpParser\Node\Expr\Array_;
+use PhpParser\Node\Scalar\String_;
 use PhpParser\Node\Stmt;
 use PhpParser\Node\Stmt\Class_;
+use PhpParser\Node\Stmt\ClassMethod;
 use PhpParser\Node\Stmt\Property;
 use PHPStan\PhpDocParser\Ast\PhpDoc\GenericTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTagNode;
 use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
 use Rector\Comments\NodeDocBlock\DocBlockUpdater;
 use Rector\Contract\Rector\ConfigurableRectorInterface;
+use Rector\PhpParser\Parser\SimplePhpParser;
 use Rector\Rector\AbstractRector;
 use Symplify\RuleDocGenerator\Exception\PoorDocumentationException;
 use Symplify\RuleDocGenerator\Exception\ShouldNotHappenException;
@@ -37,15 +45,16 @@
 /**
  * @internal
  */
-final class HasOptionsDocCommentRector extends AbstractRector implements ConfigurableRectorInterface
+final class HasOptionsRector extends AbstractRector implements ConfigurableRectorInterface
 {
     private array $classes = [
         Message::class,
     ];
 
     public function __construct(
         private DocBlockUpdater $docBlockUpdater,
-        private PhpDocInfoFactory $phpDocInfoFactory
+        private PhpDocInfoFactory $phpDocInfoFactory,
+        private SimplePhpParser $simplePhpParser,
     ) {}
 
     /**
@@ -116,29 +125,13 @@ public function getNodeTypes(): array
      */
     public function refactor(Node $node): ?Node
     {
-        /** @var class-string $class */
-        $class = $this->getName($node);
-
-        if (!$this->isSubclassesOf($class)) {
+        if (!$this->isSubclassesOf($this->getName($node))) {
             return null;
         }
 
+        $this->addMethodsOfListTypeOption($node);
         $this->sortProperties($node);
-
-        if ([] === ($defined = $this->definedFor($class))) {
-            return $node;
-        }
-
-        $phpDocInfo = $this->phpDocInfoFactory->createEmpty($node);
-
-        /** @var array<string, mixed> $allowedTypes */
-        $allowedTypes = (new \ReflectionClass($class))->getDefaultProperties()['allowedTypes'] ?? [];
-
-        foreach ($defined as $option) {
-            $phpDocInfo->addPhpDocTagNode($this->createMethodPhpDocTagNode($option, $allowedTypes[$option] ?? null));
-        }
-
-        $this->docBlockUpdater->updateRefactoredNodeWithPhpDocInfo($node);
+        $this->addPhpDocTagNodesOfMethod($node);
 
         return $node;
     }
@@ -154,6 +147,90 @@ private function isSubclassesOf(string $object): bool
         return false;
     }
 
+    /**
+     * @noinspection PhpPossiblePolymorphicInvocationInspection
+     * @noinspection D
+     *
+     * @throws \ReflectionException
+     */
+    private function addMethodsOfListTypeOption(Class_ $class): void
+    {
+        collect($this->allowedTypesFor($this->getName($class)))
+            ->filter(
+                static fn (array|string $allowedType): bool => \is_string($allowedType) && str_ends_with($allowedType, '[]')
+            )
+            ->keys()
+            ->whenNotEmpty(function (Collection $options) use ($class): void {
+                $property = collect($class->stmts)->first(
+                    fn (Stmt $stmt): bool => $stmt instanceof Property && $this->isName($stmt, 'options')
+                );
+
+                if (!$property instanceof Property) {
+                    $class->stmts[] = (new PropertyBuilder('options'))
+                        ->makeProtected()
+                        ->setType('array')
+                        ->setDefault($options->mapWithKeys(static fn (string $option): array => [$option => []])->all())
+                        ->getNode();
+
+                    return;
+                }
+
+                $options->each(function (string $option) use ($property): void {
+                    if (!($default = $property->props[0]->default) instanceof Array_) {
+                        return;
+                    }
+
+                    $arrayItem = collect($default->items)->first(
+                        fn (ArrayItem $arrayItem): bool => $this->isName($arrayItem->key, $option)
+                    );
+
+                    $arrayItem instanceof ArrayItem
+                        ? $arrayItem->value = $this->nodeFactory->createArray([])
+                        : $default->items[] = new ArrayItem(
+                            $this->nodeFactory->createArray([]),
+                            new String_($option)
+                        );
+                });
+            })
+            ->whenNotEmpty(function (Collection $options) use ($class): void {
+                $options->each(function (string $option) use ($class): void {
+                    if (
+                        collect($class->stmts)->first(
+                            fn (Stmt $stmt): bool => $stmt instanceof ClassMethod && $this->isName(
+                                $stmt,
+                                'add'.Str::studly(Pluralizer::singular($option))
+                            )
+                        ) instanceof ClassMethod
+                    ) {
+                        return;
+                    }
+
+                    /** @var list<Class_> $nodes */
+                    $nodes = $this->simplePhpParser->parseString(
+                        \sprintf(
+                            <<<'code'
+                                class Message
+                                {
+                                    public function add%s(array $%s): self
+                                    {
+                                        $this->options['%s'][] = $%s;
+
+                                        return $this;
+                                    }
+                                }
+                                code,
+                            Str::studly($singularOption = Pluralizer::singular($option)),
+                            $singularOption,
+                            $option,
+                            $singularOption,
+                        )
+                    );
+
+                    $class->stmts[] = $nodes[0]->stmts[0];
+                });
+            });
+    }
+
     private function sortProperties(Class_ $class): void
     {
         usort($class->stmts, static function (Stmt $a, Stmt $b): int {
@@ -182,6 +259,25 @@ private function sortProperties(Class_ $class): void
         });
     }
 
+    /**
+     * @throws \ReflectionException
+     */
+    private function addPhpDocTagNodesOfMethod(Class_ $node): void
+    {
+        if ([] === ($defined = $this->definedFor($class = $this->getName($node)))) {
+            return;
+        }
+
+        $phpDocInfo = $this->phpDocInfoFactory->createEmpty($node);
+        $allowedTypes = $this->allowedTypesFor($class);
+
+        foreach ($defined as $option) {
+            $phpDocInfo->addPhpDocTagNode($this->createPhpDocTagNodeOfMethod($option, $allowedTypes[$option] ?? null));
+        }
+
+        $this->docBlockUpdater->updateRefactoredNodeWithPhpDocInfo($node);
+    }
+
     /**
      * @throws \ReflectionException
      *
@@ -195,24 +291,41 @@ private function definedFor(string $class): array
             ->all();
     }
 
+    /**
+     * @throws \ReflectionException
+     *
+     * @return array<string, mixed>
+     */
+    private function allowedTypesFor(string $class): array
+    {
+        return (new \ReflectionClass($class))->getDefaultProperties()['allowedTypes'] ?? [];
+    }
+
     /**
      * @see \Symfony\Component\OptionsResolver\OptionsResolver::VALIDATION_FUNCTIONS
      *
      * @param list<string>|string $optionAllowedTypes
      */
-    private function createMethodPhpDocTagNode(string $option, null|array|string $optionAllowedTypes): PhpDocTagNode
+    private function createPhpDocTagNodeOfMethod(string $option, null|array|string $optionAllowedTypes): PhpDocTagNode
     {
         $parameter = collect([
             collect((array) ($optionAllowedTypes ?? 'mixed'))
-                ->map(static fn (string $type): array|string => match ($type) {
-                    'boolean' => 'bool',
-                    'integer', 'long' => 'int',
-                    'double', 'real' => 'float',
-                    'numeric' => ['int', 'float'],
-                    'scalar', 'resource' => 'mixed',
-                    'countable' => '\\'.\Countable::class,
-                    default => $type,
-                })
+                ->map(
+                    static fn (string $type): array|string => match (
+                        match (true) {
+                            str_ends_with($type, '[]') => $type = 'array',
+                            default => $type,
+                        }
+                    ) {
+                        'boolean' => 'bool',
+                        'integer', 'long' => 'int',
+                        'double', 'real' => 'float',
+                        'numeric' => ['int', 'float'],
+                        'scalar', 'resource' => 'mixed',
+                        'countable' => '\\'.\Countable::class,
+                        default => $type,
+                    }
+                )
                 ->flatten()
                 ->unique()
                 ->sort()
diff --git a/src/ZohoCliq/Client.php b/src/ZohoCliq/Client.php
@@ -14,11 +14,10 @@
 namespace Guanguans\Notify\ZohoCliq;
 
 /**
- * @see https://www.zoho.com/cliq/help/platform/webhook-tokens.html
  * @see https://cliq.zoho.com/integrations/webhook-tokens
+ * @see https://www.zoho.com/cliq/help/platform/webhook-tokens.html
  * @see https://www.zoho.com/cliq/help/restapi/v2/#Post_Message_Channel
  * @see https://www.zoho.com/cliq/help/restapi/v2/#Message_Object
- * @see https://www.zoho.com/cliq/help/search-results.html?query=webhook
  * @see https://www.zoho.com/cliq/help/restapi/v2/#authentication
  * @see https://github.com/Weble/ZohoClient
  * @see https://github.com/MarJose123/laravel-zoho-cliq-alert
@@ -27,7 +26,7 @@
  * curl --location 'https://cliq.zoho.com/api/v2/channelsbyname/announcements/message?zapikey=1001.4805235707f212af4b11be76483da614.d95141b05ae0550eabe503061a598' \
  * --header 'Content-Type: application/json' \
  * --data '{
- *     "text": "Welcome to Agile Bot! I'\''m here to give you a brief on what Agile is all about."
+ *     "text": "This is text."
  * }'
  * ```
  */
diff --git a/src/ZohoCliq/README.md b/src/ZohoCliq/README.md
@@ -4,7 +4,7 @@
 
 ## Related links
 
-* [https://www.zoho.com/cliq/help/platform/webhook-tokens.html](https://www.zoho.com/cliq/help/platform/webhook-tokens.html)
 * [https://cliq.zoho.com/integrations/webhook-tokens](https://cliq.zoho.com/integrations/webhook-tokens)
+* [https://www.zoho.com/cliq/help/platform/webhook-tokens.html](https://www.zoho.com/cliq/help/platform/webhook-tokens.html)
 * [https://www.zoho.com/cliq/help/restapi/v2/#Post_Message_Channel](https://www.zoho.com/cliq/help/restapi/v2/#Post_Message_Channel)
 * [https://www.zoho.com/cliq/help/restapi/v2/#Message_Object](https://www.zoho.com/cliq/help/restapi/v2/#Message_Object)
