2.7. 忽略错误

2022

2022

忽略错误

由于各种原因，你可能想要忽略 PHPStan 的报错：

• 这个报错是一个真正的问题，但你当前没有时间去重写代码库来解决。
• 必须重写 PHPStan 才能使它理解代码的作用但是现在选择不这么做。
• 这确实是一个 PHPStan 的漏洞，但你不想（也不需要）等待官方修复它。

请注意一些严重的报错（例如自动加载问题、父类不存在、解析错误等等）不能被忽略，必须在运行 PHPStan 时全部解决。

使用 PHPDocs 忽略报错

在错误代码旁加上 PHPDoc 标记的注释可以使报错被忽略：

• @phpstan-ignore-line
• @phpstan-ignore-next-line

所有的 PHP 注释风格都可以 (//，/* */，/** */) 。

function () {
    /** @phpstan-ignore-next-line */
    echo $foo;

    echo $foo; /** @phpstan-ignore-line */

    /* @phpstan-ignore-next-line */
    echo $foo;

    echo $foo; /* @phpstan-ignore-line */

    // @phpstan-ignore-next-line
    echo $foo;

    echo $foo; // @phpstan-ignore-line
};

利用配置文件忽略报错

在 配置文件 的 ignoreErrors 键里添加正则表达式可以忽略某些错误。要在整个项目通过正则表达式忽略一个错误，可以添加一个字符串条目：

parameters:
    ignoreErrors:
        - '#Call to an undefined method [a-zA-Z0-9\\_]+::doFoo\(\)#'
        - '#Call to an undefined method [a-zA-Z0-9\\_]+::doBar\(\)#'

要在指定文件用正则表达式忽略报错，可以通过 message 加 path 或者 paths 键添加条目。支持和 PHP fnmatch() 兼容的通配符模式。你可以用 count（可选，应用于 path，不适合 paths）来指定报错预计出现的次数。

parameters:
    ignoreErrors:
        -
            message: '#Access to an undefined property [a-zA-Z0-9\\_]+::\$foo#'
            path: some/dir/SomeFile.php
        -
            message: '#Call to an undefined method [a-zA-Z0-9\\_]+::doFoo\(\)#'
            path: other/dir/DifferentFile.php
            count: 2 # optional
        -
            message: '#Call to an undefined method [a-zA-Z0-9\\_]+::doBar\(\)#'
            paths:
                - some/dir/*
                - other/dir/*
        - '#Other error to ignore everywhere#'

在 path 和 paths 键指定的路径会基于配置文件所在目录解析。因此如果你的 phpstan.neon 在项目的根目录，而你想要忽略一个 src/Foo/Bar.php 文件的报错，你的路径可以简单地用 src/Foo/Bar.php。

生成一个 ignoreErrors 条目

这个有用的工具可以生成一个你可以把它放在 配置文件 的 parameters.ignoreErrors 选项的条目。它处理了直接用字符串写正则表达式，并把表达式编码成 neon 格式的复杂性。

注：这里原网页给了一个工具的示例。

基线

如果从现在开始你想忽略所有的当前错误并关注新的和有改动的代码，请移步了解基线 。

报告无用的忽略

如果一些被忽略的报错（来自配置文件 和 PHPDocs）不会再出现，PHPStan 会通知你去移除它们。你可以通过在配置中设置 reportUnmatchedIgnoredErrors 为 false 来关闭这种行为。

parameters:
    reportUnmatchedIgnoredErrors: false

排除文件

如果你的代码库包含一些有意损坏的文件（例如，为了测试您的 APP 在具有无效 PHP 代码文件上的行为），你可以用 excludePaths 键来排除它们，每个条目都符合 fnmatch() 函数的模式。

parameters:
    excludePaths:
        - tests/*/data/*

这是一个快捷方式：

parameters:
    excludePaths:
        analyseAndScan:
            - tests/*/data/*

如果你的项目目录结构混合了你自己的代码（想要分析和修复）和第三方的代码（你用来定位符号，但不想分析)，文件结构可能是这样的：

├── phpstan.neon
└── src
    ├── foo.php
    ├── ...
    └── thirdparty
        └── bar.php

这种情况下，你想要分析整个 src 目录，但不想分析 src/thirdparty 目录。可以在 PHPStan 这么配置：

parameters:
    paths:
        - src
    excludePaths:
        analyse:
            - src/thirdparty

此外，可能会有一个 src/broken 目录，它包含了你不想分析的或者仅用来定位符号的文件。 你可以这样修改配置来达到目的。

parameters:
    paths:
        - src
    excludePaths:
        analyse:
            - src/thirdparty
        analyseAndScan:
            - src/broken