
# Laravel Pint

- [简介](#introduction)
- [安装](#installation)
- [运行 Pint](#running-pint)
- [配置 Pint](#configuring-pint)
    - [预设规则集](#presets)
    - [规则](#rules)
    - [排除文件 / 文件夹](#excluding-files-or-folders)
- [持续集成](#continuous-integration)
    - [GitHub Actions](#running-tests-on-github-actions)

## 简介

[Laravel Pint](https://github.com/laravel/pint) 是一款遵循特定风格规范、专为追求简洁的开发者设计的 PHP 代码风格修复工具。

Pint 基于 [PHP CS Fixer](https://github.com/FriendsOfPHP/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 将使用计算机上所有可用的 CPU 核心：

```shell
./vendor/bin/pint --parallel --max-processes=4
```



你还可以指定要运行 Pint 的文件或目录：

```shell
./vendor/bin/pint app/Models

./vendor/bin/pint app/Models/User.php
```

Pint 会详细列出所有经过修改的文件。
如果希望查看更多关于 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 会根据这些规则修复代码中的风格问题。默认情况下，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](https://github.com/FriendsOfPHP/PHP-CS-Fixer) 构建。
因此，你可以使用 PHP CS Fixer 提供的任何规则来修复项目中的代码风格问题。具体规则可以参考：[PHP CS Fixer 配置工具](https://mlocati.github.io/php-cs-fixer-configurator)。



#### 自定义规则

除了 PHP CS Fixer 提供的规则外，Pint 还提供了一些以 `Pint/` 为前缀的自定义规则。

这些规则默认不会启用，但你可以在 `pint.json` 文件中手动启用它们。

##### `Pint/phpdoc_type_annotations_only`

此规则会删除代码中的所有注释和文档块描述文字，只保留包含 `@` 注解的行，例如 `@param`、`@return`、`@var`、`@phpstan-type` 等：

```php
/**
 * 获取用户的文章。[tl! remove]
 * [tl! remove]
 * @return HasMany<Post, $this>
 */
public function posts(): HasMany
```

不包含 `@` 注解的单行注释和块注释将被完全删除。
如果你希望保留某条特定注释，可以在注释前添加 `@note`、`@warning` 或 `@todo` 前缀：

```php
// @note 此注释将被保留。
```

要启用此规则，请将其添加到项目的 `pint.json` 文件中：

```json
{
    "preset": "laravel",
    "rules": {
        "Pint/phpdoc_type_annotations_only": true
    }
}
```

> [!注意]
> 此规则会自动跳过 `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](https://github.com/features/actions)，使其在每次向 GitHub 推送新代码时自动运行 Pint。

首先，请确保在 GitHub 中为工作流授予 **Read and write permissions（读取和写入权限）**。

设置路径：

**Settings > Actions > General > Workflow permissions**

然后，创建 `.github/workflows/lint.yml` 文件，并添加以下内容：

```yaml
name: 修复代码风格

on: [push]

jobs:
  lint:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: true
      matrix:
        php: [8.4]

    steps:
      - name: 检出代码
        uses: actions/checkout@v5

      - name: 配置 PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          tools: pint

      - name: 运行 Pint
        run: pint

      - name: 提交修复后的文件
        uses: stefanzweifel/git-auto-commit-action@v6
```

