composer-normalize 是一个 PHP 项目格式化工具，1. 统一 composer.json 缩进为 4 空格；2. 按标准顺序排列键；3. 清理多余符号；4. 验证语法并提示缺失字段；5. 支持项目内安装、CI 检查与 Git 钩子集成，确保团队协作中配置文件一致，提升可读性与版本控制效率。
在团队协作开发中，composer.json 文件是 PHP 项目依赖管理的核心。不同开发者可能因编辑器格式化规则、手动修改习惯不一，导致该文件结构混乱、缩进不一致、键顺序错乱等问题。这不仅影响可读性，还容易在 Git 提交中产生无意义的差异。为解决这一问题，composer-normalize 成为了规范配置文件格式的实用工具。
什么是 composer-normalize？
composer-normalize 是一个由 localheinz 开发并维护的 Composer 插件，它能自动分析并标准化 composer.json（以及可选的 composer.lock）文件的格式。它会执行以下操作：
- 统一 JSON 缩进为 4 个空格
- 确保属性按推荐顺序排列（如 name、description、type、license 等）
- 移除多余的空白行或逗号
- 验证 JSON 语法正确性
- 添加缺失的推荐字段提示（如 license）
最终生成一个结构清晰、格式统一的配置文件，便于团队阅读和版本控制追踪。
安装与使用方式
你可以在项目级别或全局安装该工具。推荐在项目中作为开发依赖引入，以确保所有协作者使用相同版本。
运行以下命令进行安装：
composer require --dev localheinz/composer-normalize
安装完成后，即可使用 normalize 命令：
composer normalize
执行后，工具会自动检测当前目录下的 composer.json 并进行格式化。如果文件已有不一致，它会直接修改保存。
若想仅检查是否需要格式化而不实际修改，可使用：
composer normalize --dry-run
该命令常用于 CI 流程中做质量检查。
集成到开发流程中
为了让规范生效，建议将 composer-normalize 融入日常开发习惯和自动化流程：
- 在 composer.json 中定义 scripts，例如：
"scripts": {
"check-format": "composer normalize --dry-run",
"format": "composer normalize"
} - 在 Git 钩子（如 pre-commit）中调用
composer normalize，确保每次提交前自动格式化 - 在 CI/CD 流水线中加入
--dry-run检查，若格式不一致则中断构建
处理多包项目与自定义规则
对于包含多个 composer.json 的 monorepo 项目，该工具支持递归扫描子目录。只需在根目录运行命令，它会自动发现并处理所有有效的配置文件。
虽然默认规则已覆盖大多数场景，但你也可以通过配置文件 .composer-normalize.json 自定义部分行为，例如是否忽略某些字段排序、是否启用 lock 文件校验等。
基本上就这些。使用 composer-normalize 后，团队不再需要争论“谁的格式更正确”，Composer 配置文件的整洁性由工具保障，协作效率自然提升。不复杂但容易忽略。
