PHP Scoper 是一个独立的PHP CLI工具，用于在打包阶段重写代码及依赖的命名空间以实现隔离；它不参与composer install流程，必须显式执行且需正确配置finders、prefix和dump-autoload等选项。
PHP Scoper 是什么，为什么不能直接用 Composer install
PHP Scoper 不是 Composer 的子命令，也不是 composer.json 里配个字段就能生效的工具。它是一个独立的 PHP CLI 工具，作用是在打包阶段把你的代码 + 所有依赖的命名空间全部重写（加前缀），让它们和宿主环境或其他插件彻底隔开。你运行 composer install 只是下载依赖，根本不会触发任何重命名操作。
常见错误现象：
– 写完 "php-scoper": "^4.0" 放进 composer.json 的 require-dev，以为装上就自动隔离了
– 把 scoper.php 配置文件丢进项目根目录，但没手动执行 php-scoper 命令
– 在 CI 里只跑 composer install，漏掉 scoping 步骤，导致打包后仍冲突
- 必须显式调用
php-scoperCLI，通常在构建/打包环节执行 - 它不修改原始源码，而是生成一个全新输出目录（比如
build/），所有文件都已重命名 - Composer 只负责依赖管理，Scoper 负责代码改造 —— 二者职责完全分离
怎么配置 scoper.php 让 vendor 里的类真正带上前缀
默认配置下，PHP Scoper 不会处理 vendor/ 里的代码 —— 它只扫描你指定的源目录（如 src/）。要让依赖也被重命名，得手动告诉它哪些包需要“纳入作用域”，否则 monolog/monolog 还是 MonologLogger，根本没隔离。
关键点在于 finders 和 patchers 的组合使用：
立即学习“PHP免费学习笔记（深入）”；
- 用
Finder::create()->files()->in('vendor/symfony/console')显式加入你想处理的 vendor 包路径 - 在
expose-global-constants设为false，避免全局常量泄露（比如JSON_THROW_ON_ERROR） -
prefix必须设成非空字符串，例如'MyApp'；空值或null会导致跳过重命名 - 如果用了
autoload自动加载机制（如 PSR-4），记得同步更新build/下的composer.json中的autoload配置，否则 require 时报错 Class not found
示例片段（scoper.php）：
return [
'prefix' => 'MyApp',
'finders' => [
Finder::create()->files()->in('src'),
Finder::create()->files()->in('vendor/symfony/console'),
Finder::create()->files()->in('vendor/monolog/monolog'),
],
'expose-global-constants' => false,
];
为什么 scoped 后的代码 require 失败：autoload 没跟上
PHP Scoper 生成的 build/ 目录里，类名变了（比如 MonologLogger → MyAppMonologLogger），但 composer.json 里的 autoload 规则还是旧的，require 'build/autoload.php' 就会找不到类 —— 这是最常卡住人的地方。
Scoper 默认会为你生成一份新的 autoload.php，但它依赖你是否启用了 dump-autoload 选项：
- 必须开启
'dump-autoload' => true，否则不会生成build/vendor/autoload.php - 生成的 autoloader 默认按 PSR-4 映射新前缀，比如
"MyApp\Monolog\" => "monolog/monolog/src/" - 如果你的项目用了 classmap 或 files 加载方式，Scoper 不会自动转换它们，得手动补到
scoper.php的autoload配置里 - 别直接 require 原项目的
vendor/autoload.php，scoped 后必须用build/vendor/autoload.php
PHP Scoper 和 Composer 的 autoloader 冲突怎么办
当你的项目既要支持本地开发（用原 vendor），又要发布 scoped 包（用 build/），很容易在同一个进程里混用两个 autoloader，结果类被重复定义，报 Fatal error: Cannot declare class ... because the name is already in use。
这不是 Scoper 的 bug，而是加载顺序问题：
- 不要在 scoped 包里再
require __DIR__.'/../../vendor/autoload.php'—— 这等于把原始类又载入一遍 - scoped 后的代码应完全脱离原始 vendor，所有依赖都从
build/vendor/加载 - 如果必须共存（比如插件系统），用
class_exists('MyAppMonologLogger', false)控制性加载，避免自动触发 autoload - 注意 Composer 的
autoloader-suffix配置对 Scoper 无效，它只影响composer dump-autoload生成的文件名，不改变命名空间
最稳的做法：scoped 包对外只暴露一个入口文件（如 myapp.phar 或 build/index.php），里面只 require 自己的 autoload.php，彻底切断和外部 autoloader 的联系。
