Laravel Pint

什么是 Laravel Pint

Laravel Pint 是基于 PHP CS Fixer 构建的代码风格自动修复工具。它以「无需配置即可上手」为目标进行设计，会依照 Laravel 编码风格自动格式化代码。将团队开发中常见的「代码风格 review 评论」自动化，可以让大家专注于更本质的代码评审。

安装

新创建的 Laravel 应用中已经默认安装了 Pint。对于旧版本项目，可以通过 Composer 安装。

composer require laravel/pint --dev

运行方式

基本用法

自动修复项目中所有的 .php 文件。

./vendor/bin/pint

也可以只对特定文件或目录进行处理。

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

选项一览

选项	说明
`--test`	不修改文件，仅检测风格错误。若存在错误则返回非零退出码
`--dirty`	只对 Git 中未提交的文件进行处理
`--diff=[branch]`	只处理与指定分支有差异的文件
`--repair`	修复风格错误的同时，若产生修复则返回非零退出码
`--parallel`	并行执行模式（实验性），提升性能
`--max-processes=4`	与 `--parallel` 一起使用，指定最大进程数
`-v`	显示修改的详细信息
`--config`	指定要使用的 `pint.json` 路径
`--preset`	指定要使用的预设

# 只检查不修改
./vendor/bin/pint --test

# 只处理未提交的文件
./vendor/bin/pint --dirty

# 并行运行
./vendor/bin/pint --parallel

配置

在项目根目录创建 pint.json 可以自定义行为。

{
    "preset": "laravel"
}

也可以显式指定配置文件路径。

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

预设

预设即一组规则的集合。默认是 laravel 预设，包含最适合 Laravel 项目的规则。

预设	说明
`laravel`	Laravel 推荐的编码风格（默认）
`psr12`	PSR-12 编码标准
`per`	PER Coding Style
`symfony`	Symfony 编码风格
`empty`	不带任何规则，可自行逐条定义

# 通过命令行指定预设
./vendor/bin/pint --preset psr12

自定义规则

pint.json 可以逐条启用或关闭规则。可用规则请参阅 PHP CS Fixer Configurator。

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

排除文件或目录

可以从检查中排除特定目录。

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

按文件名模式排除可以使用 notName。

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

按特定文件路径排除可以使用 notPath。

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

推荐配置

以下是一份在实际开发中效果不错的 pint.json 配置示例。

{
    "preset": "laravel",
    "rules": {
        "no_unused_imports": false,
        "strict_comparison": true,
        "declare_strict_types": true
    }
}

各规则的目的说明：

规则	作用
`no_unused_imports`	设置为 `false` 时，不会删除未使用的 `use`。Pint 的默认值为 `true`（会删除），常规 Laravel 项目通常无需重复配置
`strict_comparison`	将 `==` 转为 `===`、`!=` 转为 `!==`，避免意外的类型转换 bug
`declare_strict_types`	在文件开头自动添加 `declare(strict_types=1);`，提升类型安全性

strict_comparison 与 declare_strict_types 会强制更严格的类型代码，若在已有项目中启用，首次修改量可能较大。新项目建议一开始就引入。

no_unused_imports 主要面向包开发场景。 Pint 默认已经是 true（删除未使用的 use），因此常规 Laravel 项目并不需要显式配置。在包开发中，可能会通过 trait 或接口导入来开关功能，此时先加上 false，再根据各包实际情况改为 true 更加灵活。

在 composer.json 中注册脚本

在 composer.json 中注册 pint 相关脚本后，就可以直接通过 composer pint 执行。

{
    "scripts": {
        "pint": "./vendor/bin/pint",
        "pint:test": "./vendor/bin/pint --test"
    }
}

注册后可像下面这样运行：

# 自动修复
composer pint

# 仅检查（不修改）
composer pint:test

在 CI 环境中可以使用 composer pint:test，它会在不修改文件的情况下检测风格违规。--test 选项在有错误时会返回非零退出码，可用于 CI 的通过判断。

在 GitHub Actions 中自动执行

可以借助 GitHub Actions，在每次推送时自动修复代码风格并提交。

设置 Workflow 权限

在 GitHub 仓库 Settings > Actions > General > Workflow permissions 中启用「Read and write permissions」。

创建 Workflow 文件

创建 .github/workflows/lint.yml。

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

该工作流会在每次推送时运行 Pint，并自动提交修复后的文件。

由于在 Pull Request 评审前就完成了自动修复，可以显著减少关于代码风格的评论。团队引入时，先在本地对全部文件修复一次，再添加工作流，可以避免额外的提交。

架构

数据库

Eloquent

安全

事件

邮件与通知

支付

异步处理

实时通信

调度

缓存与优化

国际化

文件与存储

调试与监控

控制台与 CLI

性能

前端

AI 开发

开发环境

什么是 Laravel Pint

安装

运行方式

基本用法

选项一览

配置

预设

自定义规则

排除文件或目录

推荐配置

在 composer.json 中注册脚本

在 GitHub Actions 中自动执行

​什么是 Laravel Pint

​安装

​运行方式

​基本用法

​选项一览

​配置

​预设

​自定义规则

​排除文件或目录

​推荐配置

​在 composer.json 中注册脚本

​在 GitHub Actions 中自动执行

什么是 Laravel Pint

安装

运行方式

基本用法

选项一览

配置

预设

自定义规则

排除文件或目录

推荐配置

在 composer.json 中注册脚本

在 GitHub Actions 中自动执行