Composer Vendor覆盖报错：无法声明类，类名已被占用

问题背景 #

我之前修改Vendor文件的流程是：将需要修改的文件复制到项目根目录的vendor-override目录，修改composer.json，把原Vendor文件加入exclude-from-classmap，自定义文件加入files配置，示例配置如下：

"autoload": {
    "psr-4": {
        "App\\": "app/",
        "Database\\Factories\\": "database/factories/",
        "Database\\Seeders\\": "database/seeders/",
        "Routes\\Web\\": "routes/web/"
    },
    "exclude-from-classmap": [
        "vendor/area17/twill/src/Models/Model.php",
        "vendor/area17/twill/src/Models/Media.php"
    ],
    "files": [
        "vendor-override/twill/Model.php",
        "vendor-override/twill/Media.php"
    ]
},

现在要修改的vendor/area17/twill/src/Models/Media.php继承自同目录的Model.php，执行composer dump-autoload时触发类重复声明错误：

PHP Fatal error:  Cannot declare class A17\Twill\Models\Model, because the name is already in use in C:\Database\SourceDB\modulbau-shop\vendor-override\twill\Model.php on line 23

删除Vendor目录下的Model.php和Media.php后，又出现类找不到的错误：

In Media.php line 12:
                                            
  [Error]                                   
  Class "A17\Twill\Models\Model" not found  
                                            

Exception trace:
  at C:\Database\SourceDB\modulbau-shop\vendor-override\twill\Media.php:12
 require() at C:\Database\SourceDB\modulbau-shop\vendor\composer\autoload_real.php:41
 {closure}() at C:\Database\SourceDB\modulbau-shop\vendor\composer\autoload_real.php:45

尝试给Media.php添加显式use语句无效，已经排除原文件，仍无法解决问题。

解决方案 #

1. 重构vendor-override目录结构 #

按照原类的命名空间，重新组织自定义文件的存放路径：

• 原类A17\Twill\Models\Model对应路径为vendor/area17/twill/src/Models/Model.php
• 在项目根目录创建vendor-override/twill/src/Models/目录，将修改后的Model.php和Media.php放入该目录，保持与原Vendor文件的目录结构完全一致。

2. 修改composer.json的自动加载配置 #

移除原来的exclude-from-classmap和files相关配置，改用PSR-4规则优先加载自定义类：

"autoload": {
    "psr-4": {
        "App\\": "app/",
        "Database\\Factories\\": "database/factories/",
        "Database\\Seeders\\": "database/seeders/",
        "Routes\\Web\\": "routes/web/",
        "A17\\Twill\\": "vendor-override/twill/src/"
    }
}

3. 更新Composer自动加载 #

执行以下命令刷新自动加载规则：

composer dump-autoload

原理说明 #

• 原方法中exclude-from-classmap无法完全阻止Composer通过原包的PSR-4规则加载类，导致自定义类与原类重复声明。
• 自定义PSR-4规则会让Composer优先在vendor-override目录下查找A17\Twill命名空间的类，找不到才去Vendor目录加载，从根源避免了类冲突和找不到的问题。
• 无需删除Vendor目录下的原文件，Composer更新依赖时也不会影响自定义修改。

内容的提问来源于stack exchange，提问作者Knittely