Laravel 13.x 中文文档

主题

Laravel Pint ​

简介 ​

Laravel Pint 是一个为极简主义者打造的固执己见的 PHP 代码风格修复器。Pint 构建在 PHP CS Fixer 之上，使确保您的代码风格保持干净和一致变得简单。

Pint 会随所有新的 Laravel 应用程序自动安装，因此您可以立即开始使用它。默认情况下，Pint 不需要任何配置，将按照 Laravel 的固执己见的编码风格修复代码中的代码风格问题。

安装 ​

Pint 包含在 Laravel 框架的最新版本中，因此通常不需要安装。但是，对于旧应用程序，您可以通过 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 将显示它更新的所有文件的详尽列表。您可以在调用 Pint 时提供 -v 选项来查看有关 Pint 更改的更多详细信息：

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/phpdoc_type_annotations_only ​

此规则从代码中删除所有注释和文档块文本，只保留包含 @ 注解的行，如 @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
    }
}

NOTE

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

排除文件/文件夹 ​

默认情况下，Pint 将检查项目中的所有 .php 文件，但 vendor 目录中的文件除外。如果您希望排除更多文件夹，可以使用 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 中为工作流授予「读写权限」。然后，创建一个包含以下内容的 .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