is_wp_error() rule (#95)

Author: johnbillion

extension.neon

@@ -77,6 +77,7 @@ services:
             - phpstan.broker.dynamicFunctionReturnTypeExtension
 rules:
     - SzepeViktor\PHPStan\WordPress\HookDocsRule
+    - SzepeViktor\PHPStan\WordPress\IsWpErrorRule
 parameters:
     bootstrapFiles:
         - %rootDir%/../../php-stubs/wordpress-stubs/wordpress-stubs.php

src/IsWpErrorRule.php

@@ -0,0 +1,91 @@
+<?php
+
+/**
+ * Custom rule to validate usage of `is_wp_error()`.
+ */
+
+declare(strict_types=1);
+
+namespace SzepeViktor\PHPStan\WordPress;
+
+use PhpParser\Node\Expr\FuncCall;
+use PhpParser\Node;
+use PHPStan\Analyser\Scope;
+use PHPStan\Rules\RuleErrorBuilder;
+use PHPStan\Rules\RuleLevelHelper;
+use PHPStan\Type\ObjectType;
+use PHPStan\Type\VerbosityLevel;
+
+use function sprintf;
+
+/**
+ * @implements \PHPStan\Rules\Rule<\PhpParser\Node\Expr\FuncCall>
+ */
+class IsWpErrorRule implements \PHPStan\Rules\Rule
+{
+    /** @var \PHPStan\Rules\RuleLevelHelper */
+    protected $ruleLevelHelper;
+
+    public function __construct(
+        RuleLevelHelper $ruleLevelHelper
+    ) {
+        $this->ruleLevelHelper = $ruleLevelHelper;
+    }
+
+    public function getNodeType(): string
+    {
+        return FuncCall::class;
+    }
+
+    /**
+     * @param \PhpParser\Node\Expr\FuncCall $node
+     * @param \PHPStan\Analyser\Scope       $scope
+     * @return array<int, \PHPStan\Rules\RuleError>
+     */
+    public function processNode(Node $node, Scope $scope): array
+    {
+        $name = $node->name;
+
+        if (! ($name instanceof \PhpParser\Node\Name)) {
+            return [];
+        }
+
+        if ($name->toString() !== 'is_wp_error') {
+            return [];
+        }
+
+        $args = $node->getArgs();
+
+        if (! isset($args[0])) {
+            return [];
+        }
+
+        $argumentType = $scope->getType($args[0]->value);
+        $accepted = $this->ruleLevelHelper->accepts(
+            $argumentType,
+            new ObjectType('WP_Error'),
+            $scope->isDeclareStrictTypes()
+        );
+
+        if (!$accepted) {
+            return [
+                RuleErrorBuilder::message(
+                    sprintf(
+                        'is_wp_error(%s) will always evaluate to false.',
+                        $argumentType->describe(VerbosityLevel::typeOnly())
+                    )
+                )->build(),
+            ];
+        }
+
+        if (($argumentType instanceof ObjectType) && ($argumentType->getClassName() === 'WP_Error')) {
+            return [
+                RuleErrorBuilder::message(
+                    'is_wp_error(WP_Error) will always evaluate to true.'
+                )->build(),
+            ];
+        }
+
+        return [];
+    }
+}

tests/IsWpErrorRuleTest.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SzepeViktor\PHPStan\WordPress\Tests;
+
+use PHPStan\Rules\RuleLevelHelper;
+use SzepeViktor\PHPStan\WordPress\IsWpErrorRule;
+
+/**
+ * @extends \PHPStan\Testing\RuleTestCase<\SzepeViktor\PHPStan\WordPress\IsWpErrorRule>
+ */
+class IsWpErrorRuleTest extends \PHPStan\Testing\RuleTestCase
+{
+    protected function getRule(): \PHPStan\Rules\Rule
+    {
+        /** @var \PHPStan\Rules\RuleLevelHelper */
+        $ruleLevelHelper = self::getContainer()->getByType(RuleLevelHelper::class);
+
+        // getRule() method needs to return an instance of the tested rule
+        return new IsWpErrorRule($ruleLevelHelper);
+    }
+
+    // phpcs:ignore NeutronStandard.Functions.LongFunction.LongFunction
+    public function testRule(): void
+    {
+        // first argument: path to the example file that contains some errors that should be reported by IsWpErrorRule
+        // second argument: an array of expected errors,
+        // each error consists of the asserted error message, and the asserted error file line
+        $this->analyse(
+            [
+                __DIR__ . '/data/is_wp_error.php',
+            ],
+            [
+                [
+                    'is_wp_error(int) will always evaluate to false.',
+                    23,
+                ],
+                [
+                    'is_wp_error(int|false) will always evaluate to false.',
+                    24,
+                ],
+                [
+                    'is_wp_error(WP_Error) will always evaluate to true.',
+                    25,
+                ],
+                [
+                    'is_wp_error(WP_Post) will always evaluate to false.',
+                    26,
+                ],
+            ]
+        );
+    }
+}

tests/data/is_wp_error.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SzepeViktor\PHPStan\WordPress\Tests;
+
+/** @var mixed $mixed */
+$mixed = $mixed;
+
+/** @var \WP_Error|int $yes */
+$yes = $yes;
+
+/** @var int|false $no */
+$no = $no;
+
+/** @var \WP_Post $post */
+$post = $post;
+
+/** @var \WP_Error $always */
+$always = $always;
+
+// Incorrect usage:
+is_wp_error(123);
+is_wp_error($no);
+is_wp_error($always);
+is_wp_error($post);
+
+// Correct usage:
+is_wp_error($mixed);
+is_wp_error($yes);