PhpStorm 2021.3 Help

诗篇

PhpStorm 通过与Psalm工具的集成提供代码质量检查，该工具根据一组验证规则验证您的代码的一致性。

要在 PhpStorm 中使用 Psalm 而不是命令行，您需要在 PhpStorm 中注册它并将其配置为 PhpStorm代码检查。一旦在 PhpStorm 中安装并启用，该工具就可以在任何打开的 PHP 文件中使用，并且不需要额外的步骤来启动它。文件中的每次更新都会激活动态代码检查，因此可以轻松摆脱发现的问题。

Psalm 即时报告的错误和警告显示为弹出消息。当该工具以批处理模式运行时，错误和警告会显示在“问题”工具窗口中。每条消息都有psalm前缀以将其与 PhpStorm 内部检查区分开来。

Psalm 集成是通过开源 Psalm 插件实现的。该插件与 PhpStorm 捆绑在一起，默认启用。

先决条件

在将 Psalm 集成到 PhpStorm 之前，请确保满足以下先决条件：

  • 必须将包含 PHP 引擎可执行文件的目录添加到系统中path。这允许代码质量工具脚本执行对系统范围的 PHP 引擎的调用。

  • 对于基于 Docker Compose 的远程解释器，请确保使用execmode 以避免产生额外的容器。

    1. 在设置/首选项对话框 ( Ctrl+Alt+S) 中，转到PHP。

    2. 在打开的PHP页面上，单击CLI 解释器列表浏览按钮旁边的。

    3. 在打开的CLI 解释器对话框中，将所选解释器的生命周期模式设置为连接到现有容器 ('docker-compose exec')。

      docker-compose exec 用于 PHP 解释器

安装和配置 Psalm

Psalm 脚本可以用作本地脚本、与 PHP 解释器关联的脚本，或者声明为项目依赖项并通过Composer安装的脚本，这是首选和推荐的方式。

使用 Composer 安装 Psalm

在开始之前，请确保 Composer 已安装在您的计算机上并在当前项目中初始化，如Composer 依赖项管理器中所述。

当您使用 Composer 安装 Psalm 时，PhpStorm 会自动下载必要的脚本，在 IDE 中注册它们，并且可以选择启用和配置相应的代码检查。

  1. 在composer.json中，将vimeo/psalm依赖记录添加到requireorrequire-dev部分。按Ctrl+Space以获得包名称和版本的代码完成。

  2. 执行以下操作之一：

    • 单击编辑器面板顶部的安装快捷方式链接。

    • 如果启用了未安装的 Composer 包检查，PhpStorm 将突出显示当前未安装的已声明依赖项。按Alt+Enter并选择是否要一次安装特定依赖项或所有依赖项。

点击composer.json设置/首选项按钮编辑器 gutter中包记录旁边的跳转到对应的Settings/Preferences页面，手动配置 Psalm。

composer.json 中 psalm 设置的装订线图标

重置诗篇配置

初始配置 Psalm 后，composer.json中的进一步修改不会影响检查配置。要应用更新的更改，请重置 Psalm 配置。

  1. 在设置/首选项对话框 ( Ctrl+Alt+S) 中，导航到PHP | 质量工具。

  2. 在打开的质量工具页面上，展开诗篇区域并单击配置列表浏览按钮旁边的。

  3. 在打开的Psalm对话框中，清空Psalm path字段。

    空的诗篇路径字段

  4. 通过单击composer.json编辑器面板顶部的更新来更新项目 Composer 依赖项。有关详细信息，请参阅更新依赖项。

PhpStorm 将重新执行 Psalm 配置，从而应用composer.json中的更改。

手动配置 Psalm

您可以使用手动下载的本地 PHP 代码质量工具脚本或与 PHP 解释器关联的脚本。可以有许多本地和远程 PHP 解释器，在Settings/Preferences对话框的PHP页面上指定的解释器被认为是Project Default。在配置远程 PHP 解释器或配置本地 PHP 解释器中了解有关配置 PHP 解释器的更多信息。

选择要使用的诗篇脚本

  1. 在设置/首选项对话框 ( Ctrl+Alt+S) 中，导航到PHP | 质量工具。

  2. 在打开的质量工具页面上，展开诗篇区域。从配置列表中，选择 Psalm 脚本：

    • 要使用与特定远程 PHP 解释器关联的脚本，请选择该解释器的名称。

    • 要使用本地脚本，请选择Local。在这种情况下，无论项目中使用的是本地还是远程的 PHP 解释器，都会执行本地 Psalm。请注意，Psalm 只能有一个本地配置，因为 PhpStorm 运行包含 PHP 引擎路径的脚本（适用于 Windows的psalm.bat或适用于 Linux 和 macOS 的psalm ）。

    • 要使用与默认项目解释器关联的脚本，即在设置/首选项对话框的PHP页面上选择的脚本，请选择默认项目解释器。

配置本地 Psalm 脚本

  1. 下载并安装诗篇脚本。

    要检查 Psalm 安装，请切换到安装目录并运行以下命令：

    诗篇——版本

    如果该工具可用，您将收到以下格式的消息：

    诗篇 3.17.1@8f2117914813e4dc89ff4ed372785ce93b902fd1

  2. 在 PhpStorm 中注册本地 Psalm 脚本：

    • 在设置/首选项对话框 ( Ctrl+Alt+S) 中，导航到PHP | 质量工具。

    • 在打开的质量工具页面上，展开诗篇区域并单击配置列表浏览按钮旁边的。

    • 在打开的Psalm对话框中，在Psalm path字段中指定psalm.bat或psalm Psalm 可执行文件的位置。手动键入路径或单击并在打开的对话框中选择相关文件夹。浏览按钮

      要检查psalm.bat或psalm的指定路径确保 PhpStorm 和 Psalm 之间的交互，即可以从 PhpStorm 启动该工具，并且 PhpStorm 将从它接收问题报告，请单击“验证”按钮。此验证等同于运行psalm --version命令。如果验证成功通过，PhpStorm 会显示检测到的 Psalm 版本信息。

  3. 如有必要，在Tool process timeout字段中，指定您希望 PhpStorm 等待 Psalm 的结果多长时间，然后终止进程以防止 CPU 和内存使用过多。

配置与 PHP 解释器关联的 Psalm 脚本

  1. 在设置/首选项对话框 ( Ctrl+Alt+S) 中，转到PHP | 质量工具。

  2. 在打开的质量工具页面上，展开诗篇区域并单击配置列表浏览按钮旁边的。Psalm对话框打开，在左侧窗格中显示所有已配置的 Psalm 脚本列表，其中一个是Local类型，其他以与脚本关联的 PHP 解释器命名。

  3. 单击添加按钮工具栏上的 。在打开的Psalm by Remote Interpreter对话框中，选择远程 PHP 解释器以使用关联的脚本。如果列表不包含相关解释器，请单击浏览按钮并在CLI 解释器对话框中配置远程解释器，如配置远程 PHP 解释器中所述。

    当您单击OK时，PhpStorm 会将您带回Psalm对话框，其中新的Psalm配置已添加到列表中，右侧窗格显示选择的远程 PHP 解释器、与之关联的 Psalm 的路径以及高级 Psalm 选项.

  4. 如有必要，在Tool process timeout字段中，指定您希望 PhpStorm 等待 Psalm 的结果多长时间，然后终止进程以防止 CPU 和内存使用过多。

将 Psalm 配置为 PhpStorm 检查

使用 Composer 配置 Psalm 检查

您可以在composer.json的脚本部分中包含有关 Psalm 配置文件的信息。当您安装或更新项目依赖项时，将检测指定的配置文件并自动启用Psalm 验证检查。

如果没有在composer.jsonscripts部分指定配置文件，PhpStorm 将额外检查项目根目录以找到具有 psalm.xml或psalm.xml.dist默认名称的规则集。

  • 在composer.jsonscripts部分中，将Psalm 启动命令添加到叶元素之一中。psalm

    提供--config参数和配置文件的路径：

    “脚本”：{“psalm”：“vendor/bin/psalm --config=psalm.xml”}

手动配置 Psalm 检查

  1. 在Settings/Preferences对话框 ( Ctrl+Alt+S) 中，单击Editor下的Inspections。

  2. 在打开的检查页面上，展开PHP | Quality Tools节点并选择Psalm validation旁边的复选框。

  3. 在页面的右侧窗格中，使用选项区域中的控件配置 Psalm 工具：

    1. 从Severity列表中，选择 Psalm 检查的严重程度。选定的值决定了 PhpStorm 处理检测到的差异的严重程度并显示在检查结果中。

    2. 从范围列表中，选择将检查应用程序限制到的范围。

    3. 在配置文件字段中，提供Psalm 配置文件的路径。如果该文件不存在，PhpStorm 会显示提示您创建它的通知。

      找不到诗篇配置通知

    4. 选择Show info复选框，让 Psalm 报告低于配置文件中指定的errorLevel级别的错误。如果未选中该复选框，则此类错误将被忽略。

    5. 选择查找未使用的代码复选框让 Psalm 报告找到的未使用的代码（包括未使用的变量）。

    6. 选中查找未使用的@psalm-suppress 注释复选框以让 Psalm 报告所有未使用的 @psalm-suppress注释。

初始化 Psalm 缓存

虽然Psalm 验证检查可以在单个文件上运行，但 Psalm 仍将通过整个项目。在大型项目中，第一次运行时等待 Psalm 响应可能会超过Psalm对话框中工具进程超时字段中指定的限制。在这种情况下，PhpStorm 会显示错误消息：

诗篇验证检查超时错误

  • 单击Init cache链接让 Psalm 对整个项目进行传递，并在配置的缓存目录中生成缓存。如果您使用的是远程解释器，请确保将缓存目录设置为可从远程环境中访问的位置。

  • 单击从 Psalm 分析中排除链接以将当前文件添加到忽略的文件列表中。

以批处理模式运行 Psalm

  1. 从主菜单中，选择代码 | 检查代码。

  2. 从列表中选择检查配置文件，或单击以在打开的检查对话框中浏览按钮配置新配置文件。您还可以单击以检查将应用哪些修复，并确保启用了Psalm 验证检查。浏览按钮

  3. 在问题工具窗口中查看检查结果。Psalm 报告的错误和警告带有前缀，以区别于 PhpStorm 内部检查。

从 Psalm 验证检查中排除文件

当等待 Psalm 响应超过Psalm对话框中Tool process timeout字段中指定的限制时，PhpStorm 建议将文件添加到忽略列表中。

  1. 在设置/首选项对话框 ( Ctrl+Alt+S) 中，导航到PHP | 质量工具。

  2. 在打开的质量工具页面上，展开诗篇区域并单击显示忽略的文件链接。

    • 要添加文件，请单击添加按钮并在打开的对话框中找到所需的文件。

    • 要从列表中删除文件并让 Psalm 再次处理它，请选择该文件并单击删除按钮。

    • 要从列表中删除所有文件，请单击关闭按钮。

使用扩展的 @psalm 注释

除了常规的PHPDoc 注释，PhpStorm 还支持Psalm 特定的注释，这些注释被 Psalm 用于执行代码分析。指定注释时，大多数情况下可以省略该@psalm-部分。要使用代码完成，请按Ctrl+Space。

提供诗篇注释

类型支持

您可以将Psalm 类型注释用于伪类型，例如numeric或scalar为 PhpStorm 提供额外的类型信息。

提供伪型 Psalm 注释

通过@psalm-paramor@psalm-var标记提供类型定义时，您可以将常量的值联合 ( |) 和通配符 ( *) 用于共享公共前缀的常量。

提供常量值联合 Psalm 注释

泛型支持

使用@template 注释，您可以在 PhpStorm 中引入基本的泛型支持。初始支持涵盖了一个简单的函数返回其参数之一的情况。

提供模板诗篇注释
最后修改时间：2021 年 11 月 22 日
PHPStan PHP 命令行工具