README

在您的 WordPress 插件或主题中使用 Composer 可以受益。但这也带来了与其他插件或主题依赖项冲突的危险。幸运的是，一个名为PHP Scoper的强大工具将所有需要的依赖项添加到您的命名空间中，以防止冲突。不幸的是，配置相当复杂，因此我们创建了 Composer 插件，以便在 WordPress 项目中轻松指定作用域。

PHP Scoper 的问题在于它还会指定全局函数、常量和类。通常，这是您想要的，但也意味着 WordPress 函数、类和常量将被指定。此 Composer 插件解决了这个问题。它有一个最新的数据库，包含所有我们希望保持未指定作用域的 WordPress 和 WooCommerce 符号。

要求

• wpify/scoper:3.1
  • PHP 7.4 || 8.0
• wpify/scoper:3.2
  • PHP >= 8.1

使用方法

1. 此 composer 插件旨在全局安装，但您也可以将其作为开发依赖项要求。
2. 配置需要创建 composer-deps.json 文件，该文件结构与 composer.json 文件完全相同，但仅用于指定作用域依赖项。您不希望指定作用域的依赖项将放入 composer.json。
3. 将 extra.wpify-scoper.prefix 添加到您的 composer.json 中，您可以在其中指定依赖项所在的命名空间。所有其他配置选项（folder、globals、composerjson、composerlock、autorun）都是可选的。
4. 在开发环境中使用 scoper 的最简单方法是安装 WPify Scoper 作为开发依赖项。每次执行 composer install 或 composer update 后，都会为您指定 composer-deps.json 中指定的所有依赖项指定作用域。
5. 在您的 composer.json 和 composer-deps.json 中添加一个 config.platform 选项。此设置将确保依赖项将使用正确的 PHP 版本安装。

具有默认值的 composer.json 示例

{
  "config": {
    "platform": {
      "php": "8.0.30"
    }
  },
  "scripts": {
    "wpify-scoper": "wpify-scoper"
  },
  "extra": {
    "wpify-scoper": {
      "prefix": "MyNamespaceForDeps",
      "folder": "deps",
      "globals": [
        "wordpress",
        "woocommerce", 
        "action-scheduler", 
        "wp-cli"
      ],
      "composerjson": "composer-deps.json",
      "composerlock": "composer-deps.lock",
      "autorun": true
    }
  }
}

1. 选项 autorun 默认为 true，因此作用域将在执行 composer 的 update 或 install 命令时自动运行。在所有情况下，您可能不需要这样做，因此您可以将它设置为 false。要手动启动前缀，您需要在 composer.json 的 "scripts" 部分添加例如 "wpify-scoper": "wpify-scoper" 行。然后，使用命令 composer wpify-scoper install 或 composer wpify-scoper update 运行脚本。

2. 指定作用域的依赖项将在您的项目的 deps 文件夹中。您必须同时包含指定作用域的自定义自动加载和 composer 自动加载。

3. 之后，您就可以使用命名空间使用依赖项了。

PHP 文件示例

<?php
require_once __DIR__ . '/deps/scoper-autoload.php';
require_once __DIR__ . '/deps/autoload.php';
require_once __DIR__ . '/vendor/autoload.php';

new \MyNamespaceForDeps\Example\Dependency();

部署

使用 Gitlab CI 部署

要使用 Gitlab CI 与 WPify Scoper 一起使用，您可以在 .gitlab-ci.yml 文件中添加以下作业

composer:
  stage: .pre
  image: composer:2
  artifacts:
    paths:
      - $CI_PROJECT_DIR/deps
      - $CI_PROJECT_DIR/vendor
    expire_in: 1 week
  script:
    - PATH=$(composer global config bin-dir --absolute --quiet):$PATH
    - composer global config --no-plugins allow-plugins.wpify/scoper true
    - composer global require wpify/scoper
    - composer install --prefer-dist --optimize-autoloader --no-ansi --no-interaction --no-dev

使用 Github Actions 部署

要使用 Github Actions 与 WPify Scoper 一起使用，您可以在 action.yml 文件中添加以下操作

name: Build vendor

jobs:
  install:
    runs-on: ubuntu-20.04

    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Cache Composer dependencies
        uses: actions/cache@v2
        with:
          path: /tmp/composer-cache
          key: ${{ runner.os }}-${{ hashFiles('**/composer.lock') }}

      - name: Install composer
        uses: php-actions/composer@v6
        with:
          php_extensions: json
          version: 2
          dev: no
      - run: composer global config --no-plugins allow-plugins.wpify/scoper true
      - run: composer global require wpify/scoper
      - run: sudo chown -R $USER:$USER $GITHUB_WORKSPACE/vendor
      - run: composer install --no-dev --optimize-autoloader

      - name: Archive plugin artifacts
        uses: actions/upload-artifact@v2
        with:
          name: vendor
          path: |
            deps/
            vendor/

高级配置

PHP Scoper 提供了丰富的 配置选项。您可以通过在项目根目录创建 scoper.custom.php 文件来修改这个配置数组。该文件应包含 customize_php_scoper_config 函数，其中第一个参数是预先配置的配置数组。期望的输出是有效的 PHP Scoper 配置数组。

示例 scoper.custom.php 文件

<?php

function customize_php_scoper_config( array $config ): array {
    $config['patchers'][] = function( string $filePath, string $prefix, string $content ): string {
        if ( strpos( $filePath, 'guzzlehttp/guzzle/src/Handler/CurlFactory.php' ) !== false ) {
            $content = str_replace( 'stream_for($sink)', 'Utils::streamFor()', $content );
        }
        
        return $content;
    };
    
    return $config;
}