README

Aviary是一个Composer插件，用于隔离（隔离）WordPress插件和主题的依赖项。在底层，它使用PHP Scoper的最新版本。实现基于WPify Scoper，我们对其进行了修改以适应Kestrel工作流程。

为什么选择Aviary？

问题

在WordPress插件或主题中使用Composer一直具有挑战性，因为可能会与其他插件或主题发生依赖冲突。与JS / node模块不同，PHP / composer没有内置机制来隔离（或范围）依赖项。

例如，给定2个插件，它们都在composer.json中要求illuminate/support，但版本不同 - PHP将加载第一个加载的插件的版本并忽略其他版本。如果在两个版本之间存在破坏性更改，可能会导致网站损坏。

（一般）解决方案

解决这个问题的一种方法是为依赖项的命名空间添加前缀。例如

原始命名空间：Illuminate\Support\Carbon
插件1中的命名空间：MyPluginDeps\Illuminate\Support\Carbon
插件2中的命名空间：MyOtherPluginDeps\Illuminate\Support\Carbon

这样，两个插件都可以要求完全不同的illuminate/support版本而不会发生冲突，PHP将加载这两个依赖项。

有一些工具可以帮助这样做，例如

PHP Scoper
Mozart（不再维护）
PHP Prefixer

现有解决方案的问题

我们尝试了所有这些，但没有一个现成的工作。PHP Scoper最接近我们所需要的，但它被设计为用作构建步骤工具。这意味着它旨在在部署之前对代码进行范围限制，而不是在开发期间。

我们希望有一个工作流程，可以在开发过程中范围依赖项，这样我们就可以在不发生冲突的情况下本地工作多个插件。这也有助于确保我们在本地捕获任何范围问题（有时确实会发生），而不是在部署插件之后。

PHP Scoper的另一个问题是，它还会范围全局函数、常量和类。通常，这是你所希望的，但这也意味着WordPress函数、类和常量将被范围限制。由于WordPress是一个共享所有插件和主题的全局依赖项，因此它应该保持未范围限制。同样，对于WooCommerce和任何其他全局要求也是如此。

Aviary如何解决这个问题

Aviary在底层使用PHP Scoper，但解决了上述问题

它在安装或更新依赖项时进行范围限制（在开发期间）。
它有一个几乎包含所有我们想要保留未范围限制的WordPress和WooCommerce符号的数据库。
它还支持要求未范围限制的开发依赖项

要求

PHP >= 8.2

安装

在我们标记版本之前，您需要像下面这样编辑您的项目composer.json

{
   "require": {
      "kestrelwp/aviary": "dev-main"
   },
   "config": {
      "allow-plugins": {
         "kestrelwp/aviary": true
      }
   },
}

然后，运行composer install。

用法

Aviary需要2个Composer文件

composer.json - 这是一个标准的Composer文件，您用于您的项目。所有基本包配置都应在此处，包括Aviary配置。不应范围限制的依赖项（例如开发依赖项）应在此处。
composer-scoped.json - 这是一个包含您想要限定的依赖项的文件。

入门指南

将 extra.aviary.prefix 添加到 composer.json 以指定将作为依赖项前缀的命名空间

{
    "extra": {
        "aviary": {
            "prefix": "MyPrefixForDependencies"
        }
    }
}

创建包含您想要限定的依赖项以及平台要求的 composer-scoped.json。例如

{
    "config": {
        "platform": {
            "php": "7.4" // this will hint composer to install versions compatible with the specified PHP version
        }
    },
    "require": {
        "guzzlehttp/guzzle": "^7.0"
    }
}

运行 composer install 或 composer update 以安装/更新依赖项并对其进行前缀。
在您的主插件文件中，从 vendor-scoped 文件夹中 require aviary-autoload.php 文件（不需要包含任何其他自动加载器）
```
require_once __DIR__ . '/vendor-scoped/aviary-autoload.php';
```

在您的代码中使用前缀依赖项

use MyPrefixForDependencies\GuzzleHttp\Client;

手动运行

要手动执行前缀，您需要将 "aviary": "aviary" 添加到您的 composer.json 文件的 "scripts" 部分。然后使用命令 composer aviary install 或 composer aviary update 运行脚本。

注意事项

目前，您无法使用 composer require 通过 CLI 安装限定的依赖项。您需要将它们添加到 composer-scoped.json 中，然后运行 composer install 或 composer update。

配置

Aviary 使用合理的默认值进行配置，但您可以通过在您的 composer.json 中添加以下内容来自定义它

{
    "extra": {
        "aviary": {
            "prefix": "MyPrefixForDependencies",
            // The folder where the dependencies will be installed
            "folder": "vendor-scoped",
            // List of global dependencies that should not be scoped (for now, only WordPress and WooCommerce are supported)
            "globals": [
                "wordpress",
                "woocommerce"
            ],
           // The name of the composer.json file that contains the dependencies that should be scoped
            "composerjson": "composer-scoped.json",
            "composerlock": "composer-scoped.lock",
           // Whether to run scoping automatically on composer install/update
            "autorun": true
        }
    }
}

平台要求和平台检查。

您可以在 composer.json 和 composer-scoped.json 中要求不同的 PHP 平台。例如，Aviary 本身需要 PHP 8.2，但许多 WordPress 插件可能需要支持 PHP 7.4。在这种情况下，单独在 composer.json 和 composer-scoped.json 中配置平台值是完全有效的。

Composer 具有内置的平台检查，如果网站在不受支持的 PHP 版本上加载，则会产生一个致命错误。这通常不是您在生产网站上想要的，因为它会阻止整个网站加载，如果任何一个插件需要更高的 PHP 版本。

为了禁用平台检查，您可以在您的 composer.json 和 composer-scoped.json 中添加以下内容

{
    "config": {
        "platform-check": false
    }
}

注意：禁用两个都是非常重要的，因为 Aviary 需要加载限定的和非限定的自动加载器。如果 composer.json 需要 PHP 8.2，而 composer-scoped.json 需要 PHP 7.4，并且 composer.json 中未禁用平台检查，则在网站加载时将抛出致命错误。

禁用 composer 的平台检查可能也是一个好主意。这将允许网站在不受支持的 PHP 版本上加载，但您将负责检查

高级配置

PHP Scoper 有很多配置选项。您可以通过在项目根目录中创建 aviary.custom.php 文件来修改此配置数组。该文件应包含 customize_php_scoper_config 函数，其中第一个参数是预配置的配置数组。预期输出是有效的 PHP Scoper 配置数组。

示例 aviary.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;
}

开发

更新符号数据库

符号数据库是所有不应限定的 WordPress 和 WooCommerce 类、函数和常量的列表。它用于生成 PHP Scoper 配置文件。数据库存储在 symbols 文件夹中，并通过运行 composer extract 脚本生成。

注意：为了保持数据库的最新状态，我们应该在 composer.json 文件中保持 WordPress 和 WooCommerce 依赖项的最新状态。

待办事项：我们应该自动化此过程，并在数据库更新时自动生成新的 Aviary 版本。

部署

使用 GitHub Actions 进行部署

要使用 Aviary 与 GitHub Actions，您可以添加以下操作

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.kestrelwp/aviary true
      - run: composer global require kestrelwp/aviary
      - 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: |
            vendor-scoped/
            vendor/

kestrelwp / aviary

维护者

详细信息