PHP中的形式语言验证：利用PHP AST实现对特定框架约定的语法校验

大家好，今天我们来聊聊一个比较高级但非常实用的PHP话题：利用PHP抽象语法树（AST）来实现对特定框架约定的语法校验。这是一项在大型项目中保证代码质量、遵循框架规范的重要技术。

为什么需要形式语言验证？

在一个大型的PHP项目中，特别是使用框架的项目中，开发者众多，代码风格和规范很容易出现不一致。这种不一致会导致以下问题：

可读性差： 不同的代码风格增加了理解代码的难度。
维护成本高： 不一致的代码风格使得代码修改和维护变得更加困难。
潜在的错误： 不符合框架约定的代码可能导致运行时错误。
性能问题： 某些框架约定旨在优化性能，不遵循这些约定可能会降低性能。

形式语言验证可以帮助我们自动化地检测代码是否符合特定的语法规则和框架约定，从而避免上述问题。简单来说，形式语言验证就是定义一套严格的语法规则，然后使用程序来检查代码是否违反这些规则。

抽象语法树（AST）简介

在深入了解如何进行形式语言验证之前，我们需要先了解什么是抽象语法树（AST）。

AST是源代码语法结构的一种树状表示形式。编译器或解释器在解析源代码时，会生成AST。 AST 忽略了源代码中的一些细节（例如空格、注释），只保留了程序结构的关键信息。

举个简单的例子，对于PHP代码 1 + 2 * 3;，其对应的AST可能如下所示：

BinaryOp (+)
  Literal (1)
  BinaryOp (*)
    Literal (2)
    Literal (3)

这个AST表示了表达式的运算顺序：先计算 2 * 3，然后将结果与 1 相加。

PHP 提供了 nikic/php-parser 扩展包，可以用于将 PHP 代码解析成 AST。

使用 `nikic/php-parser` 生成 AST

首先，我们需要安装 nikic/php-parser 扩展包：

composer require nikic/php-parser

安装完成后，我们可以使用以下代码将 PHP 代码解析成 AST：

<?php

require_once 'vendor/autoload.php';

use PhpParserParserFactory;
use PhpParserNodeDumper;

$code = <<<'CODE'
<?php

namespace AppController;

use SymfonyBundleFrameworkBundleControllerAbstractController;
use SymfonyComponentHttpFoundationResponse;
use SymfonyComponentRoutingAnnotationRoute;

class MyController extends AbstractController
{
    #[Route('/my-route', name: 'my_route')]
    public function index(): Response
    {
        return $this->render('my_template.html.twig', [
            'message' => 'Hello, world!',
        ]);
    }
}
CODE;

$parser = (new ParserFactory)->create(ParserFactory::PREFER_PHP7);
try {
    $ast = $parser->parse($code);
} catch (PhpParserError $error) {
    echo "Parsing error: {$error->getMessage()}n";
    exit(1);
}

$dumper = new NodeDumper();
echo $dumper->dump($ast) . "n";

这段代码首先创建了一个 Parser 实例，然后使用 parse() 方法将 PHP 代码解析成 AST。如果解析过程中出现错误，则会抛出 PhpParserError 异常。最后，使用 NodeDumper 将 AST 打印出来。

运行这段代码，你将会看到类似下面的输出：

array(
    0: PhpParserNodeStmtNamespace_ {
        name: PhpParserNodeName {
            parts: array(
                0: "App",
                1: "Controller",
            )
        }
        stmts: array(
            0: PhpParserNodeStmtUse_ {
                uses: array(
                    0: PhpParserNodeStmtUseUse {
                        name: PhpParserNodeName {
                            parts: array(
                                0: "Symfony",
                                1: "Bundle",
                                2: "FrameworkBundle",
                                3: "Controller",
                                4: "AbstractController",
                            )
                        }
                        alias: null
                        attributes: array(
                        )
                    }
                )
                type: 0
                attributes: array(
                )
            }
            1: PhpParserNodeStmtUse_ {
                uses: array(
                    0: PhpParserNodeStmtUseUse {
                        name: PhpParserNodeName {
                            parts: array(
                                0: "Symfony",
                                1: "Component",
                                2: "HttpFoundation",
                                3: "Response",
                            )
                        }
                        alias: null
                        attributes: array(
                        )
                    }
                )
                type: 0
                attributes: array(
                )
            }
            2: PhpParserNodeStmtUse_ {
                uses: array(
                    0: PhpParserNodeStmtUseUse {
                        name: PhpParserNodeName {
                            parts: array(
                                0: "Symfony",
                                1: "Component",
                                2: "Routing",
                                3: "Annotation",
                                4: "Route",
                            )
                        }
                        alias: null
                        attributes: array(
                        )
                    }
                )
                type: 0
                attributes: array(
                )
            }
            3: PhpParserNodeStmtClass_ {
                flags: 0
                name: PhpParserNodeIdentifier {
                    name: "MyController"
                    attributes: array(
                    )
                }
                extends: PhpParserNodeName {
                    parts: array(
                        0: "AbstractController",
                    )
                }
                implements: array(
                )
                uses: array(
                )
                stmts: array(
                    0: PhpParserNodeStmtClassMethod {
                        flags: 1
                        byRef: false
                        name: PhpParserNodeIdentifier {
                            name: "index"
                            attributes: array(
                            )
                        }
                        params: array(
                        )
                        returnType: PhpParserNodeName {
                            parts: array(
                                0: "Response",
                            )
                        }
                        stmts: array(
                            0: PhpParserNodeStmtReturn_ {
                                expr: PhpParserNodeExprMethodCall {
                                    var: PhpParserNodeExprPropertyFetch {
                                        var: PhpParserNodeExprVariable {
                                            name: "this"
                                            attributes: array(
                                            )
                                        }
                                        name: PhpParserNodeIdentifier {
                                            name: "render"
                                            attributes: array(
                                            )
                                        }
                                        attributes: array(
                                        )
                                    }
                                    name: PhpParserNodeIdentifier {
                                        name: "render"
                                        attributes: array(
                                        )
                                    }
                                    args: array(
                                        0: PhpParserNodeArg {
                                            value: PhpParserNodeScalarString_ {
                                                value: "my_template.html.twig"
                                                attributes: array(
                                                )
                                            }
                                            byRef: false
                                            unpack: false
                                            attributes: array(
                                            )
                                        }
                                        1: PhpParserNodeArg {
                                            value: PhpParserNodeExprArray_ {
                                                items: array(
                                                    0: PhpParserNodeExprArrayItem {
                                                        key: PhpParserNodeScalarString_ {
                                                            value: "message"
                                                            attributes: array(
                                                            )
                                                        }
                                                        value: PhpParserNodeScalarString_ {
                                                            value: "Hello, world!"
                                                            attributes: array(
                                                            )
                                                        }
                                                        byRef: false
                                                        unpack: false
                                                        attributes: array(
                                                        )
                                                    }
                                                )
                                                attributes: array(
                                                )
                                            }
                                            byRef: false
                                            unpack: false
                                            attributes: array(
                                            )
                                        }
                                    )
                                    attributes: array(
                                    )
                                }
                                attributes: array(
                                )
                            }
                        }
                        attributes: array(
                            "comments": array(
                                0: PhpParserNodeCommentDoc {
                                    text: "/**n     * @Route("/my-route", name="my_route")n     */"
                                    attributes: array(
                                    )
                                }
                            )
                        )
                    }
                )
                attributes: array(
                )
            }
        )
        attributes: array(
        )
    }
)

这个输出就是 PHP 代码对应的 AST。你可以看到，AST 中包含了代码的命名空间、类、方法、变量等信息。

形式语言验证的步骤

有了 AST，我们就可以进行形式语言验证了。形式语言验证通常包含以下步骤：

定义语法规则： 首先，我们需要定义一套语法规则，描述我们希望代码遵循的规范。
遍历 AST： 然后，我们需要遍历 AST，检查代码是否符合我们定义的语法规则。
报告错误： 如果代码违反了语法规则，我们需要报告错误信息，指出错误的位置和原因。

定义语法规则

语法规则可以根据具体的框架和项目需求来定义。例如，对于 Symfony 框架，我们可以定义以下语法规则：

Controller 必须继承 AbstractController： 所有 Controller 类必须继承 SymfonyBundleFrameworkBundleControllerAbstractController 类。
Route 必须使用注解或 attributes： 所有路由都必须使用注解或 attributes 来定义。
Service 必须定义为 public： 所有 Service 都必须定义为 public。
Repository 必须使用 Doctrine 的 Repository 类： 所有 Repository 类必须继承 Doctrine 的 EntityRepository 或 ServiceEntityRepository。
模板文件名必须以 .html.twig 结尾： 所有模板文件名必须以 .html.twig 结尾。

这些只是一些简单的例子，你可以根据实际情况定义更复杂的语法规则。

遍历 AST 并检查语法规则

接下来，我们需要遍历 AST，检查代码是否符合我们定义的语法规则。我们可以使用 PhpParserNodeVisitorAbstract 类来实现 AST 的遍历。

以下是一个简单的例子，用于检查 Controller 是否继承了 AbstractController：

<?php

require_once 'vendor/autoload.php';

use PhpParserNode;
use PhpParserNodeVisitorAbstract;
use PhpParserParserFactory;

class ControllerInheritanceChecker extends NodeVisitorAbstract
{
    private $errors = [];

    public function enterNode(Node $node)
    {
        if ($node instanceof NodeStmtClass_) {
            if ($node->extends instanceof NodeName) {
                $extendsName = $node->extends->toString();
                if ($extendsName !== 'AbstractController' && strpos($extendsName, 'AbstractController') === false ) {
                    $this->errors[] = [
                        'message' => 'Controller class must extend AbstractController.',
                        'line' => $node->getLine(),
                        'file' => $node->getFile(),
                    ];
                }
            } else {
                // 如果没有 extends 关键字，也算作错误
                 $this->errors[] = [
                    'message' => 'Controller class must extend AbstractController.',
                    'line' => $node->getLine(),
                    'file' => $node->getFile(),
                ];
            }
        }
        return null;
    }

    public function getErrors(): array
    {
        return $this->errors;
    }
}

$code = <<<'CODE'
<?php

namespace AppController;

use SymfonyBundleFrameworkBundleControllerAbstractController;
use SymfonyComponentHttpFoundationResponse;
use SymfonyComponentRoutingAnnotationRoute;

class MyController //extends AbstractController  // 故意注释掉
{
    #[Route('/my-route', name: 'my_route')]
    public function index(): Response
    {
        return $this->render('my_template.html.twig', [
            'message' => 'Hello, world!',
        ]);
    }
}
CODE;

$parser = (new ParserFactory)->create(ParserFactory::PREFER_PHP7);
try {
    $ast = $parser->parse($code);
} catch (PhpParserError $error) {
    echo "Parsing error: {$error->getMessage()}n";
    exit(1);
}

$checker = new ControllerInheritanceChecker();
$traverser = new PhpParserNodeTraverser();
$traverser->addVisitor($checker);
$traverser->traverse($ast);

$errors = $checker->getErrors();

if (!empty($errors)) {
    foreach ($errors as $error) {
        echo sprintf(
            "Error: %s in %s on line %dn",
            $error['message'],
            $error['file'],
            $error['line']
        );
    }
} else {
    echo "No errors found.n";
}

这段代码定义了一个 ControllerInheritanceChecker 类，它继承了 NodeVisitorAbstract 类。 enterNode() 方法会在遍历 AST 时被调用。我们可以在 enterNode() 方法中检查当前节点是否是 NodeStmtClass_ 类型的节点，如果是，则检查它是否继承了 AbstractController。

这段代码首先创建了一个 ControllerInheritanceChecker 实例，然后创建了一个 NodeTraverser 实例，并将 ControllerInheritanceChecker 实例添加到 NodeTraverser 中。最后，使用 traverse() 方法遍历 AST。

如果代码违反了语法规则，ControllerInheritanceChecker 会将错误信息添加到 $errors 数组中。最后，我们打印出错误信息。

报告错误

如果代码违反了语法规则，我们需要报告错误信息，指出错误的位置和原因。错误信息应该尽可能清晰和详细，方便开发者快速定位和解决问题。

在上面的例子中，我们使用 echo 语句来打印错误信息。在实际项目中，我们可以使用更高级的错误报告机制，例如：

记录错误日志： 将错误信息记录到日志文件中，方便后续分析。
发送邮件通知： 将错误信息发送到指定的邮箱，及时通知开发者。
集成到 CI/CD 流程中： 将形式语言验证集成到 CI/CD 流程中，自动检测代码是否符合规范。

更复杂的例子：检查 Route 注解/Attribute

现在，让我们看一个更复杂的例子：检查 Symfony 控制器中的路由定义是否使用了注解或 attributes。

<?php

require_once 'vendor/autoload.php';

use PhpParserNode;
use PhpParserNodeVisitorAbstract;
use PhpParserParserFactory;

class RouteAnnotationChecker extends NodeVisitorAbstract
{
    private $errors = [];

    public function enterNode(Node $node)
    {
        if ($node instanceof NodeStmtClassMethod) {
            $hasRouteAnnotation = false;
            // 检查注解
            if (isset($node->getDocComment()->text)) {
                $docComment = $node->getDocComment()->text;
                if (strpos($docComment, '@Route') !== false) {
                    $hasRouteAnnotation = true;
                }
            }

            // 检查 attributes (PHP 8+)
            if (property_exists($node, 'attrGroups')) {  // 兼容 PHP 7
                if(is_array($node->attrGroups) && count($node->attrGroups) > 0) {
                    foreach ($node->attrGroups as $attrGroup) {
                        foreach($attrGroup->attrs as $attribute) {
                            if ($attribute->name instanceof NodeName) {
                                if ($attribute->name->toString() === 'Route') {
                                    $hasRouteAnnotation = true;
                                    break 2; // 找到一个就跳出
                                }
                            }
                        }
                    }
                }
            }

            if (!$hasRouteAnnotation) {
                $this->errors[] = [
                    'message' => 'Method must have a @Route annotation or #[Route] attribute.',
                    'line' => $node->getLine(),
                    'file' => $node->getFile(),
                ];
            }
        }
        return null;
    }

    public function getErrors(): array
    {
        return $this->errors;
    }
}

$code = <<<'CODE'
<?php

namespace AppController;

use SymfonyBundleFrameworkBundleControllerAbstractController;
use SymfonyComponentHttpFoundationResponse;
use SymfonyComponentRoutingAnnotationRoute;

class MyController extends AbstractController
{
    //#[Route('/my-route', name: 'my_route')] //故意注释掉
    public function index(): Response
    {
        return $this->render('my_template.html.twig', [
            'message' => 'Hello, world!',
        ]);
    }
}
CODE;

$parser = (new ParserFactory)->create(ParserFactory::PREFER_PHP7);
try {
    $ast = $parser->parse($code);
} catch (PhpParserError $error) {
    echo "Parsing error: {$error->getMessage()}n";
    exit(1);
}

$checker = new RouteAnnotationChecker();
$traverser = new PhpParserNodeTraverser();
$traverser->addVisitor($checker);
$traverser->traverse($ast);

$errors = $checker->getErrors();

if (!empty($errors)) {
    foreach ($errors as $error) {
        echo sprintf(
            "Error: %s in %s on line %dn",
            $error['message'],
            $error['file'],
            $error['line']
        );
    }
} else {
    echo "No errors found.n";
}

这个例子中，RouteAnnotationChecker 类检查每个类方法是否都有 @Route 注解或 #[Route] attribute。

它首先检查是否存在文档注释，然后检查文档注释中是否包含 @Route 字符串。对于 PHP 8 及以上版本，它还检查是否存在 attrGroups 属性，并检查是否存在 Route attribute。

表格：Node 类型与对应的检查逻辑

Node 类型	检查逻辑
`NodeStmtClass_`	检查是否继承了 `AbstractController`（或其他指定的基类）。
`NodeStmtClassMethod`	检查是否存在 `@Route` 注解或 `#[Route]` attribute。
`NodeExprMethodCall`	检查方法调用是否符合特定的规则，例如：检查 `render()` 方法的第一个参数是否以 `.html.twig` 结尾。
`NodeStmtUse_`	检查 `use` 语句是否符合特定的规则，例如：禁止使用某些不推荐的类或函数。
`NodeScalarString_`	检查字符串是否符合特定的格式，例如：检查模板文件名是否以 `.html.twig` 结尾，检查 ID 是否符合 UUID 格式。

集成到 CI/CD 流程

将形式语言验证集成到 CI/CD 流程中，可以实现自动化的代码质量检查。例如，你可以在每次提交代码时，运行形式语言验证脚本，如果发现错误，则阻止代码合并。

你可以使用 Jenkins、GitLab CI、GitHub Actions 等 CI/CD 工具来实现集成。以下是一个简单的 GitHub Actions 示例：

name: Code Style Check

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  php-lint:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.1'
          extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, gd, iconv, imagick

      - name: Install Composer dependencies
        run: composer install --no-interaction --no-progress --prefer-dist

      - name: Run Code Style Check
        run: php your_code_style_checker.php  # 替换成你的代码检查脚本

这个 GitHub Actions 会在每次 push 或 pull request 时运行 your_code_style_checker.php 脚本。如果脚本返回非零的退出码，则表示代码检查失败，GitHub Actions 会将构建标记为失败。

优点和缺点

优点：

提高代码质量： 通过自动化地检查代码是否符合规范，可以提高代码质量。
降低维护成本： 一致的代码风格可以降低代码的维护成本。
减少潜在的错误： 符合框架约定的代码可以减少运行时错误。
提高团队协作效率： 统一的代码规范可以提高团队协作效率。

缺点：

需要一定的开发成本： 需要花费时间来定义语法规则和编写代码检查脚本。
可能存在误报： 形式语言验证可能会产生误报，需要人工进行验证。
可能会限制代码的灵活性： 过于严格的语法规则可能会限制代码的灵活性。

总结：形式语言验证是保证代码质量的利器

通过使用 nikic/php-parser 扩展包，我们可以将 PHP 代码解析成 AST，并利用 AST 来进行形式语言验证。形式语言验证可以帮助我们自动化地检测代码是否符合特定的语法规则和框架约定，从而提高代码质量、降低维护成本、减少潜在的错误。将代码规范检查集成到 CI/CD 流程中，可以在代码提交时自动进行检查，保证代码质量。

更进一步：自定义规则与代码自动修复

除了检查代码风格，还可以根据项目需求定制更复杂的规则，例如检查是否存在安全漏洞、检查性能问题等。甚至可以编写代码自动修复脚本，自动修复一些简单的代码风格问题，例如自动添加空格、自动调整缩进等。