README

PHP-Scoper 是一个工具，它将任何代码体（包括所有依赖项，如 vendor 目录）移动到一个新的且独立的命名空间。

目标

PHP-Scoper 的目标是确保项目的所有代码都位于一个独立的 PHP 命名空间中。这在以下情况下是必要的，例如，当构建包含自己的 vendor 依赖项的 PHAR：

• 将它们的 vendor 依赖项捆绑在一起；并且
• 从具有类似依赖项的任意 PHP 项目中加载/执行代码

当存在一个包（可能是不同版本的）同时存在于 PHAR 和执行代码中时，将使用 PHAR 中的包。这意味着这些 PHAR 运行着与其捆绑的供应商和它们与之交互的项目中的供应商之间发生冲突的风险，这可能导致由于不同或不支持的包版本而难以调试的问题。

目录

• 安装
  • Phive
  • Composer
  • Docker
  • GitHub
• 用法
• 配置
  • 前缀
  • PHP 版本
  • 输出目录
  • 查找器和路径
  • 修补程序
  • 排除文件
  • 排除符号
  • 排除命名空间
  • 暴露符号
    • 暴露命名空间
    • 暴露类
    • 暴露函数
    • 暴露常量
• 构建受限 PHAR
  • 使用 Box
  • 不使用 Box
    • 步骤 1：配置构建位置和准备 vendors
    • 步骤 2：运行 PHP-Scoper
• 建议
• 调试
• 进一步阅读
  • 如何处理未知第三方符号
  • 自动加载别名
    • 类别名
    • 函数别名
  • Laravel 支持
  • Symfony 支持
  • Wordpress 支持
• 限制
  • 动态符号
  • 日期符号
  • HereDoc 值
  • 可调用
  • 字符串值
  • 本地函数和常量遮蔽
  • Composer 自动加载器
  • Composer 插件
  • PSR-0 部分支持
  • 文件自动加载
  • 暴露/排除特性
  • 暴露/排除枚举
• 贡献
• 致谢

用法

php-scoper add-prefix

这将为当前工作目录中找到的代码中的所有相关命名空间添加前缀。添加前缀的文件将在 build 文件夹中可用。然后您可以使用添加前缀的代码来构建您的 PHAR。

警告：在添加前缀文件后，如果您依赖于 Composer 进行自动加载，则需要再次导出自动加载器。

为了更具体的示例，您可以查看 PHP-Scoper 的构建步骤在 Makefile 中，特别是如果您使用 Composer，因为在此运行 PHP-Scoper 之前和之后都有步骤需要考虑。

请参阅 TBD，深入了解 PHP-Scoper 的 makefile 中的范围和构建 PHAR。

构建受限 PHAR

使用 Box

如果您使用 Box 构建您的 PHAR，您可以使用现有的 PHP-Scoper 集成。Box 将为您处理大多数事情，因此您只需根据您的需求调整 PHP-Scoper 的配置。

不使用 Box

步骤 1：配置构建位置和准备 vendors

假设您不需要任何开发依赖项，运行

composer install --no-dev --prefer-dist

这将通过不处理不必要的文件来节省范围过程中的时间。

步骤 2：运行 PHP-Scoper

PHP-Scoper 在前缀添加过程中会将代码复制到新的位置，而不会修改您的原始代码。默认位置是 ./build。您可以使用 --output-dir 选项来更改默认位置。默认情况下，它还会生成一个随机的前缀字符串。您可以使用 --prefix 选项设置特定的前缀字符串。如果在自动化构建过程中，您可以通过设置 --force 选项来覆盖输出目录中存在的任何代码，而无需确认。

以下是在项目根目录下使用默认选项的基本命令

bin/php-scoper add-prefix

由于没有路径参数，当前工作目录将完全作用到 ./build。当然，实际的添加前缀仅限于 PHP 文件或 PHP 脚本。其他文件将保持不变，尽管我们还需要作用到某些 Composer 相关文件。

说到作用到 Composer 相关文件... 下一步是如果依赖于它，则导出 Composer 自动加载器，以确保一切按预期工作。

composer dump-autoload --working-dir build --classmap-authoritative

建议

处理隔离 PHAR 时需要管理 3 件事

• PHAR 格式：存在一些不兼容性，例如 realpath()，由于路径不是虚拟的，所以 PHAR 内的文件将不再工作。
• 隔离代码：由于 PHP 的动态特性，隔离依赖项永远不会是一件简单的事情，因此您应该有一些端到端的测试来确保隔离的代码按预期工作。您可能还需要配置排除和公开的符号或 修补程序。
• 依赖项：您正在分发哪些依赖项？通过 composer.lock 管理的良好控制的依赖项，或者您总是带着最新的依赖项分发您的应用程序？后者虽然更理想，但按设计会导致更多的脆弱性，因为任何依赖项的新版本都可能破坏某些东西（尽管变化可能符合 SemVer，但我们正在处理 PHAR 和隔离的代码）

因此，您应该至少为您的（发布的）PHAR 执行端到端的测试。

由于同时处理上述 3 个问题可能会很繁琐，因此建议为每个步骤编写多个测试。

例如，您可以同时对非隔离的 PHAR 和隔离的 PHAR 进行测试，这样您就会知道哪个步骤存在问题。如果隔离的 PHAR 不工作，您可以尝试在 PHAR 外直接测试隔离的代码，以确保作用过程没有问题。

为了检查隔离的代码是否正确工作，您有多种解决方案

• 直接使用 PHP-Scoper 时，默认情况下 PHP-Scoper 将文件存放到 build 目录。不要忘记 您需要导出 Composer 自动加载器，以便隔离的代码能正常工作！。
• 当使用 Box 时，您可以使用其 --debug 选项从 compile 命令中导出 PHAR 中分发的代码到 .box 目录。
• 当使用由 Box 或任何其他 PHAR 构建工具创建的 PHAR 时，您可以使用 Phar::extractTo() 方法。

调试

如 建议 中所述的良好分解将有助于了解问题来自哪里。然而，如果您对此有疑问或正在调整修补程序，想检查特定文件的输出结果而不执行整个作用过程，您始终可以检查单个文件的输出结果。

php-scoper inspect path/to/my-file.php

贡献

贡献指南

致谢

该项目最初由： Bernhard Schussek (@webmozart) 创建，现已转移到 Humbug 帽子下。