Composer 项目集成 php-cs-fixer 并实现提交前自动格式化需三步：本地安装为 dev 依赖、配置 .php-cs-fixer.php 规则文件、绑定 Git 钩子；推荐本地安装确保团队一致性，禁用全局安装以防版本冲突。
在 Composer 项目中集成 php-cs-fixer 并实现提交前自动格式化，核心是三步：安装工具、配置规则、绑定 Git 钩子。重点不是“能不能做”，而是让流程稳定、可复现、不干扰日常开发。
安装 php-cs-fixer 到项目本地
推荐作为 dev 依赖安装，避免全局环境差异影响团队一致性：
- 运行 composer require --dev friendsofphp/php-cs-fixer
- 安装后命令路径为 vendor/bin/php-cs-fixer（Linux/macOS）或 vendor\bin\php-cs-fixer.bat（Windows）
- 不要用全局安装（如
composer global require），否则不同项目可能因版本冲突导致格式结果不一致
定义项目专属的 .php-cs-fixer.php 配置文件
在项目根目录新建 .php-cs-fixer.php，明确指定规则和作用范围：
- 基础示例（适配 PSR-12 + PHP 8+）：
<?php
return (new PhpCsFixer\Config())
->setRules([
'@PSR12' => true,
'array_syntax' => ['syntax' => 'short'],
'declare_strict_types' => true,
'no_unused_imports' => true,
'ordered_imports' => true,
])
->setFinder(PhpCsFixer\Finder::create()
->in(['src', 'tests'])
->name('*.php')
->notName('*.blade.php')
->ignoreDotFiles(true)
->ignoreVCS(true)
)
->setCacheFile('.php-cs-fixer.cache');
-
务必设置
setCacheFile：加速后续运行，尤其对大项目明显 -
->in([...])明确限定目录，避免误处理 vendor 或生成文件 - 首次运行可加
--dry-run --diff参数预览改动，确认无意外变更
用 Composer 脚本 + Git pre-commit 钩子自动执行
不依赖第三方钩子管理器（如 Husky），用最简方式落地：
立即学习“PHP免费学习笔记（深入）”；
- 在 composer.json 的
"scripts"中添加：
"scripts": {
"cs-fix": "php-cs-fixer fix --verbose",
"cs-check": "php-cs-fixer fix --dry-run --using-cache=no"
}
- 然后在项目根目录创建 .git/hooks/pre-commit 文件（Linux/macOS）：
#!/bin/sh echo "Running PHP code style check..." if ! composer cs-check; then echo "❌ Code style violations found. Run 'composer cs-fix' to fix them." exit 1 fi
- 给钩子加执行权限：chmod +x .git/hooks/pre-commit
- Windows 用户可用 pre-commit.bat（内容类似，用
call composer cs-check） - 这个钩子只做检查（
--dry-run），失败则中断提交——更安全，避免自动修改引入意外
补充建议：CI 和团队协同
本地钩子只是第一道防线，还需配套保障：
- 在 GitHub Actions / GitLab CI 中加入 composer cs-check 步骤，防止绕过本地钩子
- 把 .php-cs-fixer.php 和 composer.json 中的脚本纳入版本管理，确保所有人用同一套规则
- 编辑器（如 VS Code）可装 PHP CS Fixer 插件并设为“保存时格式化”，但仅作辅助——以 pre-commit 钩子为准
基本上就这些。不复杂但容易忽略的是缓存文件路径和 Finder 范围，设错会导致慢或漏检。跑通一次，之后每次提交都默默守着代码风格。
