Pint
Laravel Pint
简介
Laravel Pint 是一款遵循特定风格规范、专为追求简洁的开发者设计的 PHP 代码风格修复工具。
Pint 基于 PHP CS Fixer 构建,可以轻松确保代码风格整洁且统一。
所有新创建的 Laravel 应用程序都会自动安装 Pint,因此你可以立即开始使用它。
默认情况下,Pint 无需任何配置,就能按照 Laravel 特有的代码风格规范,自动修复代码中的风格问题。
安装
在较新版本的 Laravel 框架中,已经内置了 Pint,因此通常无需单独安装。
不过,对于较旧的应用程序,你可以通过 Composer 安装 Laravel Pint:
composer require laravel/pint --dev
运行 Pint
你可以通过调用项目 vendor/bin 目录下的 pint 可执行文件,让 Pint 自动修复代码风格问题:
./vendor/bin/pint
如果希望 Pint 使用并行模式(实验性功能)来提高执行性能,可以使用 --parallel 选项:
./vendor/bin/pint --parallel
并行模式还允许你通过 --max-processes 选项指定最大进程数。如果不指定该选项,Pint 将使用计算机上所有可用的 CPU 核心:
./vendor/bin/pint --parallel --max-processes=4
你还可以指定要运行 Pint 的文件或目录:
./vendor/bin/pint app/Models
./vendor/bin/pint app/Models/User.php
Pint 会详细列出所有经过修改的文件。
如果希望查看更多关于 Pint 修改内容的详细信息,可以在执行 Pint 时添加 -v 选项:
./vendor/bin/pint -v
如果你只希望 Pint 检查代码中的风格错误,而不实际修改文件,可以使用 --test 选项。
如果发现任何代码风格错误,Pint 将返回一个非零退出码:
./vendor/bin/pint --test
如果你希望 Pint 只修改 Git 中与指定分支存在差异的文件,可以使用 --diff=[branch] 选项。
这在 CI 环境(例如 GitHub Actions)中非常有用,因为它可以只检查新增或修改过的文件,从而节省执行时间:
./vendor/bin/pint --diff=main
如果你希望 Pint 只修改 Git 中存在未提交更改的文件,可以使用 --dirty 选项:
./vendor/bin/pint --dirty
如果你希望 Pint 修复所有存在代码风格错误的文件,同时在修复了任何错误后返回非零退出码,可以使用 --repair 选项:
./vendor/bin/pint --repair
配置 Pint
如前所述,Pint 默认无需任何配置即可使用。
不过,如果你希望自定义预设规则集、具体规则或需要检查的目录,可以在项目根目录下创建一个 pint.json 文件:
{
"preset": "laravel"
}
此外,如果你希望使用指定目录中的 pint.json 配置文件,可以在执行 Pint 时通过 --config 选项指定配置文件路径:
./vendor/bin/pint --config vendor/my-company/coding-style/pint.json
预设规则集
预设规则集定义了一组规则,Pint 会根据这些规则修复代码中的风格问题。默认情况下,Pint 使用 laravel 预设规则集,按照 Laravel 特有的代码风格规范修复问题。不过,你也可以通过向 Pint 提供 --preset 选项来指定其他预设规则集:
./vendor/bin/pint --preset psr12
如果需要,也可以在项目的 pint.json 文件中设置预设规则集:
{
"preset": "psr12"
}
Pint 当前支持以下预设规则集:
-
laravel -
per -
psr12 -
symfony -
empty
规则
规则是 Pint 用于修复代码风格问题的具体规范。
如前所述,预设规则集是预先定义好的一组规则,通常已经能够满足大多数 PHP 项目的需求,因此一般不需要关注其中包含的具体规则。
不过,如果你有自定义需求,可以在 pint.json 文件中启用或禁用特定规则,也可以使用 empty 预设规则集,从零开始定义自己的规则:
{
"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 提供的任何规则来修复项目中的代码风格问题。具体规则可以参考:PHP CS Fixer 配置工具。
自定义规则
除了 PHP CS Fixer 提供的规则外,Pint 还提供了一些以 Pint/ 为前缀的自定义规则。
这些规则默认不会启用,但你可以在 pint.json 文件中手动启用它们。
Pint/phpdoc_type_annotations_only
此规则会删除代码中的所有注释和文档块描述文字,只保留包含 @ 注解的行,例如 @param、@return、@var、@phpstan-type 等:
/**
* 获取用户的文章。[tl! remove]
* [tl! remove]
* @return HasMany<Post, $this>
*/
public function posts(): HasMany
不包含 @ 注解的单行注释和块注释将被完全删除。
如果你希望保留某条特定注释,可以在注释前添加 @note、@warning 或 @todo 前缀:
// @note 此注释将被保留。
要启用此规则,请将其添加到项目的 pint.json 文件中:
{
"preset": "laravel",
"rules": {
"Pint/phpdoc_type_annotations_only": true
}
}
[!注意]
此规则会自动跳过config目录中的文件,因为配置文件通常依赖注释来提供说明文档。
排除文件 / 文件夹
默认情况下,Pint 会检查项目中所有的 .php 文件,但 vendor 目录中的文件除外。如果你希望排除更多目录,可以使用 exclude 配置选项:
{
"exclude": [
"my-specific/folder"
]
}
如果你希望排除所有文件名符合指定模式的文件,可以使用 notName 配置选项:
{
"notName": [
"*-my-file.php"
]
}
如果你希望通过指定文件的完整路径来排除某个文件,可以使用 notPath 配置选项:
{
"notPath": [
"path/to/excluded-file.php"
]
}
持续集成
GitHub Actions
为了使用 Laravel Pint 自动检查和修复项目中的代码风格,你可以配置 GitHub Actions,使其在每次向 GitHub 推送新代码时自动运行 Pint。
首先,请确保在 GitHub 中为工作流授予 Read and write permissions(读取和写入权限)。
设置路径:
Settings > Actions > General > Workflow permissions
然后,创建 .github/workflows/lint.yml 文件,并添加以下内容:
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
本译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。
Laravel 13 中文文档
关于 LearnKu
推荐文章: