应按项目安装而非全局安装，因全局安装易致版本冲突、CI/Docker 环境路径不可靠及团队格式化结果不一致；推荐执行 composer require --dev friendsofphp/php-cs-fixer，并配置 .php-cs-fixer.php 文件。
为什么不用全局安装 php-cs-fixer？
直接运行 composer global require friendsofphp/php-cs-fixer 看似省事，但实际项目中容易出问题：不同项目依赖的 PHP-CS-Fixer 版本可能冲突；全局二进制路径在某些 CI 环境或 Docker 容器里不可靠；团队成员本地环境不一致导致格式化结果不一致。
更稳妥的做法是把 php-cs-fixer 作为开发依赖，按项目安装。
如何为项目安装并配置 php-cs-fixer
进入项目根目录后执行：
composer require --dev friendsofphp/php-cs-fixer
安装完成后，php-cs-fixer 二进制文件会出现在 vendor/bin/php-cs-fixer。推荐用这个路径调用，避免版本错乱。
常见配置方式：
- 在项目根目录新建
.php-cs-fixer.php（注意不是.php_cs，后者已弃用） - 内容示例（适配 PSR-12 + Laravel 风格）：
<?php
return (new PhpCsFixer\Config())
->setRules([
'@PSR12' => true,
'array_syntax' => ['syntax' => 'short'],
'binary_operator_spaces' => ['operators' => ['=>' => 'align_single_space_minimal']],
'blank_line_before_statement' => ['statements' => ['return']],
'single_quote' => true,
])
->setFinder(
PhpCsFixer\Finder::create()
->in(['app', 'config', 'database', 'routes', 'tests'])
->name('*.php')
->notName('*.blade.php')
->ignoreDotFiles(true)
->ignoreVCS(true)
);
关键点：
• setFinder() 必须显式指定要处理的目录和文件，否则默认只扫当前目录
• ignoreVCS(true) 能跳过 .git 目录，防止报错
• 规则数组里用 @PSR12 是基础，再叠加项目定制项更可控
立即学习“PHP免费学习笔记（深入）”；
怎么安全地批量格式化又不破坏 Git 历史？
直接跑 vendor/bin/php-cs-fixer fix 可能一次性改几百个文件，Git diff 失去可读性，Code Review 难以聚焦逻辑变更。
建议分三步走：
- 先用
--dry-run --diff预览改动：vendor/bin/php-cs-fixer fix --dry-run --diff - 确认无误后，加
--verbose查看每个文件是否被处理：vendor/bin/php-cs-fixer fix --verbose - 若只想修某个文件或目录，直接指定路径：
vendor/bin/php-cs-fixer fix app/Http/Controllers/
特别注意：
• 不要在 git add . 后再运行 fix，否则未暂存的修改会被混入提交
• 如果团队用 pre-commit hook，务必把 php-cs-fixer 加入 composer.json 的 scripts 段，并用 composer run fix 统一入口
composer.json 里怎么集成成一键命令？
在 composer.json 的 "scripts" 字段里加一条：
"scripts": {
"fix": "php-cs-fixer fix --verbose",
"fix-dry": "php-cs-fixer fix --dry-run --diff"
}
这样就能用 composer run fix 执行（Composer 2.2+），旧版用 composer run-script fix。
好处是命令路径、参数、PHP 版本都由 Composer 自动管理，不需要记 vendor/bin/... 的完整路径。
容易忽略的一点：
• 如果项目用了 platform 配置（如 "php": "8.1"），php-cs-fixer 会自动匹配兼容版本，但某些新规则（如 modernize_types_casting）需要 PHP 8.0+，低版本会静默跳过 —— 建议在 CI 中明确检查 php-cs-fixer --version 和当前 PHP 版本是否匹配
