Laravel 中文文档

主题

全部文档

Laravel Pint ​

简介 ​

Laravel Pint 是面向极简主义者的、有明确主张的 PHP 代码风格修复工具。Pint 基于 PHP CS Fixer 构建，能轻松确保代码风格保持整洁一致。

所有新的 Laravel 应用都会自动安装 Pint，因此你可以立即开始使用。默认情况下，Pint 无需任何配置，会按 Laravel 主张的编码风格修复代码中的风格问题。

安装 ​

近期发布的 Laravel 框架已包含 Pint，通常无需再安装。不过对于较旧的应用，你可以通过 Composer 安装 Laravel Pint：

shell
composer require laravel/pint --dev

运行 Pint ​

你可以调用项目 vendor/bin 目录中的 pint 可执行文件，让 Pint 修复代码风格问题：

shell
./vendor/bin/pint

若希望 Pint 以并行模式（实验性）运行以提升性能，可使用 --parallel 选项：

shell
./vendor/bin/pint --parallel

并行模式还允许通过 --max-processes 选项指定最大进程数。若未提供该选项，Pint 将使用本机所有可用核心：

shell
./vendor/bin/pint --parallel --max-processes=4

你也可以对特定文件或目录运行 Pint：

shell
./vendor/bin/pint app/Models

./vendor/bin/pint app/Models/User.php

默认情况下，Pint 不会格式化 Blade 模板。若也要格式化 .blade.php 文件，可使用 --blade 选项，这会在当前运行中启用 Pint/laravel_blade 规则，而无需修改 pint.json：

shell
./vendor/bin/pint --blade

Pint 会详细列出所有已更新的文件。调用 Pint 时提供 -v 选项，可查看更详细的变更信息：

shell
./vendor/bin/pint -v

若只想让 Pint 检查代码风格错误而不实际修改文件，可使用 --test 选项。若发现任何代码风格错误，Pint 将返回非零退出码：

shell
./vendor/bin/pint --test

若只想让 Pint 修改相对给定分支（按 Git）有差异的文件，可使用 --diff=[branch] 选项。这在 CI 环境（如 GitHub Actions）中很有效，可只检查新增或已修改的文件以节省时间：

shell
./vendor/bin/pint --diff=main

若只想让 Pint 修改按 Git 有未提交变更的文件，可使用 --dirty 选项：

shell
./vendor/bin/pint --dirty

若希望 Pint 修复有代码风格错误的文件，并在修复了任何错误时以非零退出码退出，可使用 --repair 选项：

shell
./vendor/bin/pint --repair

配置 Pint ​

如前所述，Pint 无需任何配置。不过，若要自定义预设、规则或检查目录，可在项目根目录创建 pint.json 文件：

json
{
    "preset": "laravel"
}

此外，若要使用特定目录中的 pint.json，可在调用 Pint 时提供 --config 选项：

shell
./vendor/bin/pint --config vendor/my-company/coding-style/pint.json

预设 ​

预设定义了一组可用于修复代码风格问题的规则。默认情况下，Pint 使用 laravel 预设，按 Laravel 主张的编码风格修复问题。不过，你可以通过向 Pint 提供 --preset 选项来指定其他预设：

shell
./vendor/bin/pint --preset psr12

如有需要，也可以在项目的 pint.json 文件中设置预设：

json
{
    "preset": "psr12"
}

Pint 当前支持的预设为：laravel、per、psr12、symfony 与 empty。

规则 ​

规则是 Pint 用于修复代码风格问题的风格指南。如上所述，预设是预定义的规则组，对大多数 PHP 项目已足够，因此通常无需关心其中的单条规则。

不过，如有需要，你可以在 pint.json 中启用或禁用特定规则，或使用 empty 预设从头定义规则：

json
{
    "preset": "laravel",
    "rules": {
        "simplified_null_return": true,
        "array_indentation": false,
        "new_with_parentheses": {
            "anonymous_class": true,
            "named_class": true
        }
    }
}

Pint 基于 PHP CS Fixer 构建。因此，你可以使用其任意规则来修复项目中的代码风格问题：PHP CS Fixer Configurator。

自定义规则 ​

除 PHP CS Fixer 规则外，Pint 还提供以 Pint/ 为前缀的自定义规则。这些规则默认未启用，但可在 pint.json 中启用。

Pint/laravel_blade ​

此规则会格式化 Blade 模板，为 .blade.php 文件应用一致的缩进、间距与属性格式。默认情况下 Pint 不格式化 Blade 文件，因此必须在 pint.json 中启用此规则以选择加入：

json
{
    "preset": "laravel",
    "rules": {
        "Pint/laravel_blade": true
    }
}

启用后，Pint 每次运行时除 PHP 文件外，还会格式化 Blade 模板：

shell
./vendor/bin/pint

或者，若想在单次运行中启用此规则而不修改 pint.json，可使用 --blade 选项：

shell
./vendor/bin/pint --blade

该规则底层使用 Prettier 以及 prettier-plugin-blade 与 prettier-plugin-tailwindcss 插件，因此本机必须安装 Node.js。首次在启用此规则的情况下运行 Pint 时，Pint 会检测缺失的 Prettier 依赖并提示你安装。

INFO

此规则会自动跳过通常依赖自身格式的文件，例如 Laravel Boost 指南，以及位于 resources/views/emails 与 resources/views/mail 目录中的邮件视图。

Pint/phpdoc_type_annotations_only ​

此规则会移除代码中的所有注释与 docblock 叙述文字，仅保留包含 @ 注解的行，例如 @param、@return、@var、@phpstan-type 等：

php
/**
 * Get the posts for the user. [tl! remove]
 * [tl! remove]
 * @return HasMany<Post, $this>
 */
public function posts(): HasMany

不含 @ 注解的单行注释与块注释会被完全移除。若要保留特定注释，可为其加上 @note、@warning 或 @todo 前缀：

php
// @note This comment will be preserved.

要启用此规则，请将其添加到 pint.json 文件：

json
{
    "preset": "laravel",
    "rules": {
        "Pint/phpdoc_type_annotations_only": true
    }
}

INFO

此规则会自动跳过 config 目录中的文件，因为配置文件通常依赖注释作为文档。

排除文件 / 文件夹 ​

默认情况下，Pint 会检查项目中除 vendor 目录外的所有 .php 文件。若要排除更多文件夹，可使用 exclude 配置选项：

json
{
    "exclude": [
        "my-specific/folder"
    ]
}

若要排除所有符合给定名称模式的文件，可使用 notName 配置选项：

json
{
    "notName": [
        "*-my-file.php"
    ]
}

若要通过提供确切路径排除某个文件，可使用 notPath 配置选项：

json
{
    "notPath": [
        "path/to/excluded-file.php"
    ]
}

持续集成 ​

GitHub Actions ​

要使用 Laravel Pint 自动检查项目代码风格，可配置 GitHub Actions，在有新代码推送到 GitHub 时运行 Pint。首先，请在 GitHub 的 Settings > Actions > General > Workflow permissions 中为工作流授予「Read and write permissions」。然后创建 .github/workflows/lint.yml 文件，内容如下：

yaml
name: Fix Code Style

on: [push]

jobs:
  lint:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: true
      matrix:
        php: [8.4]

    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          tools: pint

      - name: Run Pint
        run: pint

      - name: Commit linted files
        uses: stefanzweifel/git-auto-commit-action@v6