PHP 代码风格自动修复神器：PHP-CS-Fixer 完整使用指南-壹联网络

项目介绍

PHP-CS-Fixer（PHP Coding Standards Fixer）是一款自动化 PHP 代码风格修复工具，能够自动将不符合编码规范的 PHP 代码修正为符合标准的样子。它是 PHP 生态中历史最悠久、使用最广泛的代码格式化工具之一，目前 GitHub 星标数超过 1.3 万。

无论是团队协作还是个人项目，代码风格统一都至关重要。手动逐个修改不仅费时费力，还容易遗漏和出错。PHP-CS-Fixer 可以自动检测并修复数百种代码风格问题，让你的代码库始终保持整洁一致。

核心特色

自动修复 300+ 代码风格问题：涵盖命名、缩进、空格、注释、语法等方方面面
多种预设规则集：开箱即用 Symfony 编码规范、PER-CS、PHP-CS-Fixer 自定规则集
仅检查不修改（Dry Run）：先用 –check 或 –dry-run 模式预览所有变更，确认无误后再实际修改
增量修复：支持仅修复有变更的文件，适合在 Git Hook 中集成
高度可配置：通过 .php-cs-fixer.php 或 .php-cs-fixer.dist.php 配置文件自定义规则
CI/CD 友好：可在 GitHub Actions、GitLab CI 等 CI 流程中自动检查代码风格
自定义规则：支持编写自定义修复规则，满足团队特殊需求

支持的 PHP 版本

PHP-CS-Fixer 支持 PHP 7.4 到 PHP 8.5，能够帮助项目在升级 PHP 版本时同步修正因语法变化带来的风格问题。最新版本还内置了 auto-PHP 迁移规则集，可以自动将代码迁移到更新版本的 PHP 语法。

安装步骤

方式一：Composer 安装（推荐）

# 作为项目开发依赖安装（推荐）
composer require --dev friendsofphp/php-cs-fixer

# 全局安装
composer global require friendsofphp/php-cs-fixer

# 独立 PHAR 文件（无需 PHP 环境）
# 访问 https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/releases 下载

方式二：Docker 使用

docker pull oskarstefansson/php-cs-fixer
docker run --rm -v $(pwd):/project oskarstefansson/php-cs-fixer fix /project

基础使用

初始化配置文件

# 在项目根目录生成默认配置文件
./vendor/bin/php-cs-fixer init

这会在项目根目录创建一个 .php-cs-fixer.php 或 .php-cs-fixer.dist.php 配置文件。

检查代码风格问题（不修改）

# 检查所有 PHP 文件
./vendor/bin/php-cs-fixer check

# 显示详细问题列表
./vendor/bin/php-cs-fixer check --diff

自动修复代码

# 修复所有 PHP 文件
./vendor/bin/php-cs-fixer fix

# 修复并显示详细 diff
./vendor/bin/php-cs-fixer fix --diff

# 只修复特定规则
./vendor/bin/php-cs-fixer fix --rules=@Symfony

# 修复指定文件或目录
./vendor/bin/php-cs-fixer fix src/
./vendor/bin/php-cs-fixer fix app/Controller.php

配置文件示例

<?php

return (new PhpCsFixer\Config())
    ->setRules([
        '@Symfony' => true,
        'array_syntax' => ['syntax' => 'short'],
        'strict_param' => true,
    ])
    ->setFinder(
        PhpCsFixer\Finder::create()
            ->exclude('vendor')
            ->in(__DIR__)
    );

常用规则集

@Symfony：Symfony 框架官方编码规范，适合大多数 PHP 项目
@PER-CS：PHP-FIG 推荐的 PER 编码风格标准
@PhpCsFixer：PHP-CS-Fixer 官方推荐的严格规则集
@auto：自动应用基础规则，适合大多数项目
@PHP71Migration：将代码迁移到 PHP 7.1 兼容风格
@PHP80Migration：将代码迁移到 PHP 8.0 兼容风格

集成到开发流程

集成到 Git Hook（推荐）

在 .git/hooks/pre-commit 中添加，在每次提交前自动检查：

#!/bin/sh
vendor/bin/php-cs-fixer fix --diff --dry-run --stop-on-violation
exit $?

集成到 GitHub Actions

name: PHP CS Fixer
on: [push, pull_request]
jobs:
  fix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: php-actions/composer@v6
      - name: Run PHP-CS-Fixer
        run: vendor/bin/php-cs-fixer check --diff