PHP-CS-Fixer PHP 代码格式化工具：完整指南与实战示例

1. 什么是 PHP-CS-Fixer？为什么需要它？

PHP-CS-Fixer（PHP Coding Standards Fixer）是一款强大的 PHP 代码自动格式化工具，能够根据指定的编码标准自动修复代码格式问题。它会分析源代码，检测格式化违规（如缩进、空格、换行、导入顺序、短语法使用等），并自动进行修正。在现代 PHP 项目开发中，尤其是团队协作场景下，这个工具不可或缺。

为什么要使用它？首先，它能确保团队代码风格统一。当多位开发者共同维护一个项目时，每个人都有自己的编码习惯。PHP-CS-Fixer 通过将代码统一为标准格式，完美解决这一问题。其次，它能节省代码审查时间：开发者无需再讨论缩进和空格问题，可以专注于业务逻辑和架构设计。最后，自动格式化能避免提交中出现"噪声"变更——修改一行代码不会导致整个文件格式被连带改动。

PHP-CS-Fixer 支持超过 100 个内置规则，并允许创建自定义规则。该工具可轻松集成到 CI/CD 流水线、版本控制系统（通过 pre-commit 钩子）和 IDE 中。它兼容 PSR-1、PSR-2、PSR-12、Symfony、Doctrine 等主流编码标准。

2. 安装方法

PHP-CS-Fixer 通过 Composer（PHP 依赖管理器）安装。建议全局安装或作为项目的开发依赖安装。

# 全局安装（推荐，可在任意项目中使用）
composer global require friendsofphp/php-cs-fixer

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

# 验证安装
php-cs-fixer --version

全局安装后，请确保 ~/.composer/vendor/bin 目录（Windows 系统为 %USERPROFILE%\AppData\Roaming\Composer\vendor\bin）已添加到系统 PATH 环境变量中。

3. 快速上手——最小化实战示例

创建一个 example.php 文件，包含以下"不整洁"的代码：

<?php
$name = "John";
$age=25;
function greet($name){
echo "Hello, ".$name;
}
greet($name);

现在使用 PHP-CS-Fixer 格式化该文件：

php-cs-fixer fix example.php --rules=@PSR12

执行后，文件内容将变为：

<?php

$name = 'John';
$age = 25;

function greet($name): void
{
    echo 'Hello, '.$name;
}

greet($name);

可以看到，PHP-CS-Fixer 在赋值运算符周围添加了空格，将双引号替换为单引号（无变量插值时），添加了返回类型 : void，规范了大括号格式，并增加了空行以提升可读性。

4. 核心方法/函数/类

4.1. PhpCsFixer\Config::create()

方法签名： public static Config::create(): Config

功能说明： 创建一个新的配置实例，用于设置格式化规则。

<?php
use PhpCsFixer\Config;

$config = Config::create()
    ->setRules([
        '@PSR12' => true,
        'array_syntax' => ['syntax' => 'short'],
    ])
    ->setFinder(
        PhpCsFixer\Finder::create()
            ->in(__DIR__ . '/src')
    );

4.2. PhpCsFixer\Finder::create()

方法签名： public static Finder::create(): Finder

功能说明： 创建一个查找器对象，用于定位需要格式化的 PHP 文件。

<?php
use PhpCsFixer\Finder;

$f