PHP的静态分析器（Psalm/PHPStan）扩展：编写自定义规则检测特定框架的API滥用

PHP静态分析：定制规则，猎杀框架API滥用

大家好，今天我们来聊聊如何使用PHP静态分析工具，例如Psalm和PHPStan，编写自定义规则来检测特定框架的API滥用。 这不仅仅是代码规范的问题，更是安全、性能和可维护性的重要保障。

1. 静态分析的必要性：防患于未然

在软件开发中，错误是不可避免的。 传统的动态测试（例如单元测试、集成测试）只能在运行时发现问题，而静态分析则可以在不运行代码的情况下，通过分析源代码来检测潜在的错误、漏洞和不良实践。 这就像一个代码审查员，在代码提交之前就帮你找出问题。

静态分析可以检测到的问题包括：

• 类型错误：例如，将字符串传递给需要整数的函数。
• 未使用的变量或函数。
• 潜在的安全漏洞：例如，SQL注入、跨站脚本攻击（XSS）。
• 代码风格问题：例如，不符合PSR规范的代码。
• 框架API滥用：这是我们今天要重点讨论的内容。

2. 框架API滥用的危害：不仅仅是代码难看

框架通常提供了强大的API，但如果不正确使用，可能会导致各种问题。例如：

• 性能问题： 错误地使用缓存机制、数据库查询优化不足等。
• 安全漏洞： 未正确转义用户输入，导致XSS或SQL注入。
• 代码可维护性降低： 使用了框架的内部API，导致升级困难。
• 业务逻辑错误： 错误地理解了框架的生命周期，导致业务逻辑不正确。

举个简单的例子，假设我们使用Laravel框架，错误地在循环中执行数据库查询：

foreach ($users as $user) {
    $role = DB::table('roles')->where('user_id', $user->id)->first(); // N+1 查询问题
    // ... 其他操作
}

这段代码会导致严重的性能问题，因为它会为每个用户执行一次数据库查询，这就是典型的N+1查询问题。静态分析可以帮助我们发现这类问题，并提供优化建议。

3. Psalm vs PHPStan：选择合适的工具

Psalm和PHPStan是两个流行的PHP静态分析工具，它们各有特点：

特性	Psalm	PHPStan
准确性	非常注重准确性，会尽可能地推断出变量的类型。	速度更快，但准确性可能略低于Psalm。
速度	相对较慢，尤其是在大型项目中。	速度更快，更适合在CI/CD流程中使用。
配置	配置相对复杂，需要编写XML配置文件。	配置相对简单，可以使用YAML配置文件。
扩展性	提供了强大的扩展机制，可以编写自定义插件。	也提供了扩展机制，但相对Psalm来说，灵活性可能稍逊一筹。
社区支持	拥有活跃的社区，提供了丰富的文档和示例。	拥有活跃的社区，提供了丰富的文档和示例。
错误报告	错误报告详细，包含了错误的位置、类型和建议。	错误报告详细，包含了错误的位置、类型和建议。
自动修复	部分错误可以自动修复。	部分错误可以自动修复。
适用场景	对代码质量要求非常高的项目，或者需要进行复杂的类型分析的项目。	对速度要求较高的项目，或者需要快速集成到CI/CD流程中的项目。

选择哪个工具取决于项目的具体需求。 如果你更注重准确性，并且愿意花更多的时间进行配置，那么Psalm可能更适合你。 如果你更注重速度，并且希望快速集成到CI/CD流程中，那么PHPStan可能更适合你。

4. 编写自定义规则：以Psalm为例

接下来，我们以Psalm为例，演示如何编写自定义规则来检测框架API滥用。

4.1 环境搭建

首先，我们需要安装Psalm：

composer require vimeo/psalm --dev

然后，我们需要创建一个Psalm的配置文件psalm.xml：

<?xml version="1.0"?>
<psalm
    errorLevel="info"
    resolveConstantTypeAliases="true"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="https://getpsalm.org/schema/config"
    xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
>
    <projectFiles>
        <directory name="src"/>
    </projectFiles>

    <plugins>
        <pluginClass class="MyCustomRulesPlugin"/>
    </plugins>
</psalm>

这个配置文件指定了要分析的代码目录（src）和要加载的插件（MyCustomRulesPlugin）。

4.2 创建插件

接下来，我们需要创建一个插件类MyCustomRulesPlugin，它负责注册我们的自定义规则：

<?php

namespace MyCustomRules;

use PsalmPluginPluginEntryPointInterface;
use PsalmPluginRegistrationInterface;

class Plugin implements PluginEntryPointInterface
{
    public function __invoke(RegistrationInterface $registration, ?SimpleXMLElement $config = null): void
    {
        $registration->registerHooksFromClass(RulesNoDatabaseQueryInLoop::class);
    }
}

这个插件类注册了一个钩子，它告诉Psalm在分析代码时，使用RulesNoDatabaseQueryInLoop类来检测错误。

4.3 创建自定义规则

现在，我们需要创建自定义规则类RulesNoDatabaseQueryInLoop，它负责检测循环中的数据库查询：

<?php

namespace MyCustomRulesRules;

use PhpParserNode;
use PhpParserNodeStmtForeach_;
use PhpParserNodeExprMethodCall;
use PsalmCodebase;
use PsalmCodeLocation;
use PsalmIssuePluginIssue;
use PsalmIssuePluginIssueData;
use PsalmPluginEventHandlerAfterExpressionAnalysisInterface;
use PsalmPluginEventHandlerEventAfterExpressionAnalysisEvent;

class NoDatabaseQueryInLoop implements AfterExpressionAnalysisInterface
{
    /**
     * Called after an expression has been analyzed
     *
     * @param AfterExpressionAnalysisEvent $event
     *
     * @return void
     */
    public static function afterExpressionAnalysis(AfterExpressionAnalysisEvent $event): void
    {
        $expr = $event->getExpr();
        $statements_analyzer = $event->getStatementsSource();
        $codebase = $event->getCodebase();

        if (!$expr instanceof MethodCall) {
            return;
        }

        if (strtolower($expr->name->name) !== 'first' && strtolower($expr->name->name) !== 'get') {
            return;
        }

        if (!($expr->var instanceof NodeExprStaticCall || $expr->var instanceof NodeExprMethodCall)) {
            return;
        }

        if ($expr->var instanceof NodeExprStaticCall && strtolower($expr->var->class->parts[0]) !== 'db') {
            return;
        }

        if ($expr->var instanceof NodeExprMethodCall && !isset($expr->var->var->name) && strtolower($expr->var->name->name) !== 'table' ) {
            return;
        }

        $node = $statements_analyzer->getNode();

        while ($node) {
            if ($node instanceof Foreach_) {
                $issue = new PluginIssue(
                    'DatabaseQueryInLoop',
                    new PluginIssueData(
                        '避免在循环中进行数据库查询，这会导致性能问题。',
                        new CodeLocation($statements_analyzer->getSource(), $expr)
                    )
                );

                $event->getStatementsSource()->addIssue($issue);

                break;
            }

            $node = $node->getAttribute('parent');
        }
    }
}

这段代码实现了AfterExpressionAnalysisInterface接口，它会在每个表达式分析之后被调用。 我们的规则会检查当前表达式是否是一个数据库查询（例如DB::table('roles')->where('user_id', $user->id)->first()），并且是否位于循环中。 如果是，则会报告一个DatabaseQueryInLoop错误。

4.4 定义Issue

我们需要定义 DatabaseQueryInLoop 这个Issue。新建文件 src/Issue/DatabaseQueryInLoop.php：

<?php

namespace MyCustomRulesIssue;

use PsalmIssuePluginIssue;

class DatabaseQueryInLoop extends PluginIssue
{
}

4.5 测试规则

现在，我们可以创建一个测试文件src/test.php：

<?php

namespace MyCustomRules;

use IlluminateSupportFacadesDB;

class Test
{
    public function test(array $users): void
    {
        foreach ($users as $user) {
            $role = DB::table('roles')->where('user_id', $user->id)->first(); // 数据库查询在循环中
            // ... 其他操作
        }
    }
}

然后，我们可以运行Psalm来分析代码：

./vendor/bin/psalm

如果一切顺利，Psalm会报告一个DatabaseQueryInLoop错误，指出在test.php文件的第10行存在数据库查询在循环中的问题。

5. 编写自定义规则：以PHPStan为例

接下来，我们以PHPStan为例，演示如何编写自定义规则来检测框架API滥用。

5.1 环境搭建

首先，我们需要安装PHPStan：

composer require phpstan/phpstan --dev

然后，我们需要创建一个PHPStan的配置文件phpstan.neon：

includes:
    - vendor/phpstan/phpstan-doctrine/extension.neon
    - vendor/phpstan/phpstan-strict-rules/rules.neon

parameters:
    level: 7
    paths:
        - src
    bootstrapFiles:
        - vendor/autoload.php
    rules:
        - MyCustomRulesRulesNoDatabaseQueryInLoopPHPStan

这个配置文件指定了要分析的代码目录（src）、要加载的启动文件（vendor/autoload.php）和要使用的规则（MyCustomRulesRulesNoDatabaseQueryInLoopPHPStan）。

5.2 创建自定义规则

现在，我们需要创建自定义规则类RulesNoDatabaseQueryInLoopPHPStan，它负责检测循环中的数据库查询：

<?php

namespace MyCustomRulesRules;

use PhpParserNode;
use PhpParserNodeStmtForeach_;
use PhpParserNodeExprMethodCall;
use PHPStanAnalyserScope;
use PHPStanRulesRule;
use PHPStanRulesRuleError;
use PHPStanRulesRuleErrorBuilder;

/**
 * @implements Rule<MethodCall>
 */
class NoDatabaseQueryInLoopPHPStan implements Rule
{
    public function getNodeType(): string
    {
        return MethodCall::class;
    }

    public function processNode(Node $node, Scope $scope): array
    {
        if (!$node instanceof MethodCall) {
            return [];
        }

        if (strtolower($node->name->name) !== 'first' && strtolower($node->name->name) !== 'get') {
            return [];
        }

        if (!($node->var instanceof NodeExprStaticCall || $node->var instanceof NodeExprMethodCall)) {
            return [];
        }

        if ($node->var instanceof NodeExprStaticCall && strtolower($node->var->class->parts[0]) !== 'db') {
            return [];
        }

        if ($node->var instanceof NodeExprMethodCall && !isset($node->var->var->name) && strtolower($node->name->name) !== 'table' ) {
            return [];
        }

        $currentNode = $node;

        while ($currentNode) {
            if ($currentNode instanceof Foreach_) {
                return [
                    RuleErrorBuilder::message('避免在循环中进行数据库查询，这会导致性能问题。')
                        ->line($node->getLine())
                        ->build(),
                ];
            }

            if ($currentNode->getAttribute('parent') === null) {
                break;
            }
            $currentNode = $currentNode->getAttribute('parent');
        }

        return [];
    }
}

这段代码实现了Rule接口，它会在每个MethodCall节点被调用。 我们的规则会检查当前表达式是否是一个数据库查询（例如DB::table('roles')->where('user_id', $user->id)->first()），并且是否位于循环中。 如果是，则会报告一个错误。

5.3 测试规则

使用与Psalm示例相同的测试文件src/test.php。

然后，我们可以运行PHPStan来分析代码：

./vendor/bin/phpstan analyse src

如果一切顺利，PHPStan会报告一个错误，指出在src/test.php文件的第10行存在数据库查询在循环中的问题。

6. 更复杂的规则：检测未转义的用户输入

除了检测循环中的数据库查询，我们还可以编写更复杂的规则来检测其他类型的框架API滥用。 例如，我们可以编写一个规则来检测未转义的用户输入，以防止XSS攻击。

以Psalm为例，我们可以创建一个新的规则类RulesNoUnescapedOutput：

<?php

namespace MyCustomRulesRules;

use PhpParserNode;
use PhpParserNodeExprEcho_;
use PhpParserNodeExprVariable;
use PsalmCodebase;
use PsalmCodeLocation;
use PsalmIssuePluginIssue;
use PsalmIssuePluginIssueData;
use PsalmPluginEventHandlerAfterExpressionAnalysisInterface;
use PsalmPluginEventHandlerEventAfterExpressionAnalysisEvent;

class NoUnescapedOutput implements AfterExpressionAnalysisInterface
{
    public static function afterExpressionAnalysis(AfterExpressionAnalysisEvent $event): void
    {
        $expr = $event->getExpr();
        $statements_analyzer = $event->getStatementsSource();
        $codebase = $event->getCodebase();

        if (!$expr instanceof Echo_) {
            return;
        }

        foreach ($expr->exprs as $expression) {
            if ($expression instanceof Variable) {
                // 检查变量是否经过转义
                if (!self::isEscaped($expression, $statements_analyzer, $codebase)) {
                    $issue = new PluginIssue(
                        'UnescapedOutput',
                        new PluginIssueData(
                            '避免直接输出未转义的用户输入，这可能导致XSS攻击。',
                            new CodeLocation($statements_analyzer->getSource(), $expression)
                        )
                    );

                    $event->getStatementsSource()->addIssue($issue);
                }
            }
        }
    }

    private static function isEscaped(Variable $variable, PsalmStatementsSource $statements_analyzer, Codebase $codebase): bool
    {
        // 这里可以添加更复杂的逻辑来判断变量是否经过转义
        // 例如，检查变量是否经过htmlspecialchars()函数处理
        // 或者检查变量是否使用了框架提供的转义方法

        // 简单的示例：假设所有以"escaped_"开头的变量都经过转义
        return strpos($variable->name, 'escaped_') === 0;
    }
}

这个规则会检查echo语句中是否直接输出了未转义的用户输入。 isEscaped()函数可以根据具体的框架和转义方法进行定制。

7. 集成到CI/CD流程：自动化代码审查

静态分析的最佳实践是将它集成到CI/CD流程中。 这样，每次代码提交时，静态分析工具都会自动运行，并报告潜在的问题。 这可以帮助我们及早发现问题，并避免将有缺陷的代码部署到生产环境。

8. 持续改进：不断完善规则

编写自定义规则是一个持续改进的过程。 随着项目的演进，我们需要不断地完善规则，以适应新的需求和挑战。 同时，我们也可以从社区中学习，借鉴其他人的经验，共同提高代码质量。

代码安全，代码质量，框架规则

静态分析工具是代码质量保证的重要组成部分。 通过编写自定义规则，我们可以检测特定框架的API滥用，提高代码的安全性、性能和可维护性。

选择工具，配置规则，持续改进

选择合适的工具（Psalm或PHPStan），编写自定义规则，并将它们集成到CI/CD流程中，是提高代码质量的有效方法。 记住，这是一个持续改进的过程。

静态分析，代码利器，安全保障

静态分析是现代软件开发中不可或缺的工具，它可以帮助我们及早发现问题，并避免将有缺陷的代码部署到生产环境。