解决Apiato项目中PHP CS Fixer无法正确排除下划线开头文件的问题

问题背景

在Apiato项目中使用PHP CS Fixer进行代码风格检查时，发现一个关于文件排除规则的配置问题。项目需要排除以下划线(_)开头的文件（如_404.v1.public.php），但现有的配置方式无法正常工作。

技术分析

PHP CS Fixer的notName()方法在设计上有一个限制：当多次调用时，实际上只有最后一次调用会生效。这是因为每次调用notName()都会覆盖之前的排除规则，而不是追加新的规则。

在Apiato项目中，原本的配置尝试通过两次调用notName()来排除两种不同模式的文件：

1. 排除以下划线开头的文件
2. 排除特定扩展名的文件

这种配置方式导致只有第二种排除规则生效，而以下划线开头的文件仍然会被检查。

解决方案

正确的做法是将所有需要排除的模式合并到一个notName()调用中，使用正则表达式的"或"操作符(|)来组合多个排除条件。具体实现如下：

->notName([
    '/^_/',          // 排除以下划线开头的文件
    '*.blade.php',   // 排除Blade模板文件
    '*.js',          // 排除JavaScript文件
    '*.html',        // 排除HTML文件
    '*.json',        // 排除JSON文件
    '*.xml',         // 排除XML文件
    '*.vue',         // 排除Vue组件文件
    '*.md',          // 排除Markdown文件
])

实际应用

在Apiato项目中，这种配置方式特别重要，因为项目遵循特定的API文档生成规范，以下划线开头的文件通常用于存放API文档的元数据定义（如@apiDefine注释块）。这些文件不需要进行代码风格检查，因为它们包含的是文档注释而非实际代码。

最佳实践建议

1. 单一调用原则：对于文件排除规则，尽量在一个notName()调用中完成所有配置
2. 正则表达式使用：对于复杂的排除模式，可以使用正则表达式来精确匹配
3. 测试验证：配置完成后，使用--dry-run参数测试规则是否按预期工作
4. 文档说明：在项目文档中明确说明哪些文件会被排除及其原因

总结

通过优化PHP CS Fixer的配置方式，Apiato项目现在能够正确排除以下划线开头的特殊文件，同时保持对其他类型文件的代码风格检查。这种改进不仅解决了当前的问题，也为项目未来的扩展提供了更灵活的配置基础。