README

Yii 配置

此 Composer 插件提供与 composer 包一起分发的配置的组装。它实现了一个插件系统，允许在安装时直接提供使用包所需的配置，以便使其开箱即用。该包成为包含代码及其默认配置的插件。

要求

• PHP 8.0 或更高版本。
• Composer 2.3 或更高版本。

安装

composer require yiisoft/config

它是如何工作的？

该包由两部分组成：Composer 插件和配置加载器。

在 composer 更新其自动加载文件之后，这通常在 dump-autoload、require、update 或 remove 之后发生，Composer 插件

• 扫描已安装的包，以查找它们 composer.json 中的 config-plugin 额外选项。
• 将合并计划写入 config/.merge-plan.php。它包括每个包的 composer.json 中的配置。

在应用程序入口点，通常是 index.php，我们创建配置加载器的实例并获取所需的配置

use Yiisoft\Config\Config;
use Yiisoft\Config\ConfigPaths;

$config = new Config(
    new ConfigPaths(dirname(__DIR__)),
);

$web = $config->get('web');

上面的 web 是一个配置组。配置加载器根据合并计划在运行时获取它。配置由三个层次组成，加载方式如下

• 每个 vendor/package-name 的供应商配置。这些提供默认值。
• 来自 config 的根包配置。这些可能覆盖供应商配置。
• 来自 config 的特定环境配置。这些可能覆盖根和供应商配置。

请注意，配置层内不允许有同名键。

在调用 get() 方法时，如果配置组不存在，将抛出 \ErrorException。如果您不确定配置组是否存在，则使用 has() 方法

use Yiisoft\Config\Config;
use Yiisoft\Config\ConfigPaths;

$config = new Config(
    new ConfigPaths(dirname(__DIR__)),
);

if ($config->has('web')) {
    $web = $config->get('web');
}

配置组

每个配置组代表一组配置，合并到单个数组中。它在每个包的 composer.json 中定义。

"extra": {
    "config-plugin": {
        "params": [
            "params.php",
            "?params-local.php"
        ],
        "common": "common.php",
        "web": [
            "$common",
            "web.php",
            "../src/Modules/*/config/web.php"
        ],
        "other": "other.php"
    }
}

在上面的示例中，映射键是配置组名称，值是配置文件和其他配置组的引用。文件路径相对于 源目录，默认情况下是 composer.json 所在的路径。

标记

• ? - 标记可选文件。未标记此标记的文件不存在将导致异常。

  "params": [
     "params.php",
     "?params-local.php"
  ]

  如果找不到 params-local.php，这是可以的，但如果找不到 params.php，则不行。

• * - 标记通配符路径。这意味着通配符掩码匹配零个或多个匹配项。

  "web": [
     "../src/Modules/*/config/web.php"
  ]

  它将收集 config 文件夹中 src/Modules/ 的任何子文件夹中的所有 web.php。然而，如果配置文件夹作为 PHAR 归档的一部分打包，则配置文件将不会被上传。在这种情况下，您必须明确指定每个配置文件。

• $ - 通过其组名引用另一个配置。

  "params": [
     "params.php",
     "?params-local.php"
  ],
  "params-console": [
     "$params",
     "params-console.php"
  ],
  "params-web": [
     "$params",
     "params-web.php"
  ]

  配置组 params-console 和 params-web 都将包含来自 params.php 和 params-local.php 的配置值，以及它们自己的配置值。

像以下这样定义您的配置

return [
    'components' => [
        'db' => [
            'class' => \my\Db::class,
            'name' => $params['db.name'],
            'password' => $params['db.password'],
        ],
    ],
];

从配置（默认情况下，组名为 params）中读取特殊变量 $params。

为 $params 使用自定义组

默认情况下，$params 变量从 params 组中读取。您可以通过 Config 构造函数自定义组名。

$config = new Config(
    new ConfigPaths(__DIR__ . '/configs'),
    null,
    [],
    'custom-params' // Group name for `$params`
);

您可以将 null 作为 $params 组名传递。在这种情况下，$params 将为空数组。

使用子配置

为了访问子配置，在您的配置中使用以下方法

'routes' => $config->get('routes');

选项

Composer 插件和配置加载器都提供了一些选项。Composer 选项在 composer.json 中指定。

"extra": {
    "config-plugin-options": {
      "source-directory": "config"
    },
    "config-plugin": {
        // ...
    }
}

source-directory

source-directory 选项指定了为指定包读取配置的位置。它适用于所有包，包括根包，通常是应用程序。该值是相对于 composer.json 文件所在路径的路径。默认值是一个空字符串。

如果您更改了根包的源目录，不要忘记在创建 Config 实例时调整配置路径。通常这是 index.php。

use Yiisoft\Config\Config;
use Yiisoft\Config\ConfigPaths;

$config = new Config(
    new ConfigPaths(dirname(__DIR__), 'path/to/config/directory'),
);

$web = $config->get('web');

vendor-override-layer

vendor-override-layer 选项向供应商添加了一个子层，该子层分配了将覆盖供应商默认配置的包。此子层位于供应商和应用层之间。

如果您需要在应用层之前重新定义默认配置，这很有用。为此，您需要创建自己的包，其中包含用于覆盖默认配置的配置。

"name": "vendor-name/package-name",
"extra": {
    "config-plugin": {
        // ...
    }
}

在您的应用的根文件 composer.json 中，指定此包在 vendor-override-layer 选项中。

"require": {
    "vendor-name/package-name": "version",
    "yiisoft/config": "version"
},
"extra": {
    "config-plugin-options": {
        "vendor-override-layer": "vendor-name/package-name"
    },
    "config-plugin": {
        // ...
    }
}

以相同的方式，可以将多个包添加到此子层。

"extra": {
    "config-plugin-options": {
        "vendor-override-layer": [
            "vendor-name/package-1",
            "vendor-name/package-2"
        ]
    }
}

如果包太多，可以使用通配符模式。

"extra": {
    "config-plugin-options": {
        "vendor-override-layer": [
            "vendor-1/*",
            "vendor-2/config-*"
        ]
    }
}

有关通配符语法的更多信息，请参阅 yiisoft/strings。

请注意，与此子层类似，其他层不允许有相同名称的键。

merge-plan-file

此选项允许您覆盖合并计划文件的路径。默认值为 .merge-plan.php。要更改它，设置值

"extra": {
    "config-plugin-options": {
        "merge-plan-file": "custom/path/my-merge-plan.php"
    }
}

这在开发时很有用。更改此选项时，不要忘记在 Config 构造函数中设置相同的路径。

build-merge-plan

build-merge-plan 选项允许您禁用创建/更新 config/.merge-plan.php。默认启用，要禁用它，将值设置为 false

"extra": {
    "config-plugin-options": {
        "build-merge-plan": false
    }
}

这在开发时很有用。如果配置包是您的包的依赖项，并且您在开发包时不需要创建合并计划文件。例如，这在 yiisoft/yii-runner 中实现。

package-types

package-types 选项定义了由 Composer 插件处理的包类型。默认为 "library" 和 "composer-plugin"。您可以通过自己的类型覆盖默认值。

"extra": {
    "config-plugin-options": {
        "package-types": ["library", "my-extension"]
    }
}

环境

插件支持创建添加到基本配置中的附加环境。这允许您为应用程序创建多个配置，例如 production 和 development。

请注意，环境仅在应用级别受支持，并且不会从包的配置中读取。

环境在您的应用程序的 composer.json 文件中指定。

"extra": {
    "config-plugin-options": {
        "source-directory": "config"
    },
    "config-plugin": {
        "params": "params.php",
        "web": "web.php"
    },
    "config-plugin-environments": {
        "dev": {
            "params": "dev/params.php",
            "app": [
                "$web",
                "dev/app.php"
            ]
        },
        "prod": {
            "app": "prod/app.php"
        }
    }
}

配置定义了合并过程。来自 config-plugin-environments 的其中一个环境与由 config-plugin 定义的默认配置合并。在给定示例中，在 dev 环境中，我们使用主环境中的 $web 配置。

此配置具有以下结构

config/             Configuration root directory.
    dev/            Development environment files.
        app.php     Development environment app group configuration.
        params.php  Development environment parameters.
    prod/           Production environment files.
        app.php     Production environment app group configuration.
    params.php      Main configuration parameters.
    web.php         Мain configuration web group configuration.

要选择要使用的环境，必须在创建 Config 实例时指定其名称。

use Yiisoft\Config\Config;
use Yiisoft\Config\ConfigPaths;

$config = new Config(
    new ConfigPaths(dirname(__DIR__)),
    'dev',
);

$app = $config->get('app');

如果在环境中定义，则 params 将与主配置中的 params 合并，并可作为所有配置中的 $params 使用。

PHP 文件中的配置

您可以在PHP文件中定义配置。要实现这一点，请在composer.json的extra部分指定PHP文件路径。

"extra": {
    "config-plugin-file": "path/to/configuration/file.php"
}

配置的指定方式相同，只是格式为PHP。

return [
    'config-plugin-options' => [
        'source-directory' => 'config',  
    ],
    'config-plugin' => [
        'params' => [
            'params.php',
            '?params-local.php',
        ],
        'web' => 'web.php', 
    ],
    'config-plugin-environments' => [
        'dev' => [
            'params' => 'dev/params.php',
            'app' => [
                '$web',
                'dev/app.php',
            ],
        ],
        'prod' => [
            'app' => 'prod/app.php',
        ],
    ],
];

如果您指定了文件路径，则composer.json中剩余的章节（config-plugin-*）将被忽略，配置将读取指定的PHP文件。路径是相对于composer.json文件所在位置。

配置修饰符

递归合并数组

默认情况下，配置文件中不执行递归合并数组。如果您想递归合并特定组（如params）中的数组，必须在Config构造函数中传递带有指定组名的RecursiveMerge修饰符。

use Yiisoft\Config\Config;
use Yiisoft\Config\ConfigPaths;
use Yiisoft\Config\Modifier\RecursiveMerge;

$config = new Config(
    new ConfigPaths(dirname(__DIR__)),
    'dev',
    [
        RecursiveMerge::groups('params', 'events', 'events-web', 'events-console'),
    ],
);

$params = $config->get('params'); // merged recursively

如果您想递归合并到一定深度，请使用RecursiveMerge::groupsWithDepth()方法。

RecursiveMerge::groups(['widgets-themes', 'my-custom-group'], 1)

注意：其他配置的引用使用根组的递归修饰符。

数组的反向合并

反向合并的结果按数据源降序排序。这对于将特定配置（例如模块的）与基本配置合并很有用，其中更具体的配置（即模块的）具有更高的优先级。其中一个例子是合并事件。

要启用反向合并，请在Config构造函数中传递带有指定组名的ReverseMerge修饰符。

use Yiisoft\Config\Config;
use Yiisoft\Config\ConfigPaths;
use Yiisoft\Config\Modifier\ReverseMerge;

$config = new Config(
    new ConfigPaths(dirname(__DIR__)),
    'dev',
    [
        ReverseMerge::groups('events', 'events-web', 'events-console'),
    ],
);

$events = $config->get('events-console'); // merged reversed

注意：其他配置的引用使用根组的反向修饰符。

从供应商包配置中删除元素

有时需要从供应商包配置中删除某些元素。为此，请将RemoveFromVendor修饰符传递给Config构造函数。

删除指定的键路径

use Yiisoft\Config\Config;
use Yiisoft\Config\ConfigPaths;
use Yiisoft\Config\Modifier\RemoveFromVendor;

$config = new Config(
    new ConfigPaths(dirname(__DIR__)),
    'dev',
    [
        // Remove elements `key-for-remove` and `nested→key→for-remove` from all groups in all vendor packages
        RemoveFromVendor::keys(
            ['key-for-remove'],
            ['nested', 'key', 'for-remove'],
        ),
        
        // Remove elements `a` and `b` from all groups in package `yiisoft/auth`
        RemoveFromVendor::keys(['a'], ['b'])
            ->package('yiisoft/auth'),
        
        // Remove elements `c` and `d` from groups `params` and `web` in package `yiisoft/view`
        RemoveFromVendor::keys(['c'], ['d'])
            ->package('yiisoft/view', 'params', 'web'),
        
        // Remove elements `e` and `f` from all groups in package `yiisoft/auth`
        // and from groups `params` and `web` in package `yiisoft/view`
        RemoveFromVendor::keys(['e'], ['f'])
            ->package('yiisoft/auth')
            ->package('yiisoft/view', 'params', 'web'),
    ],
);

$params = $config->get('params');

删除指定的配置组

use Yiisoft\Config\Config;
use Yiisoft\Config\ConfigPaths;
use Yiisoft\Config\Modifier\RemoveFromVendor;

$config = new Config(
    new ConfigPaths(dirname(__DIR__)),
    'dev',
    [
        RemoveFromVendor::groups([
            // Remove group `params` from all vendor packages
            '*' => 'params',
            
            // Remove groups `common` and `web` from all vendor packages
            '*' => ['common', 'web'],
            
            // Remove all groups from package `yiisoft/auth`
            'yiisoft/auth' => '*',
            
            // Remove groups `params` from package `yiisoft/http`
            'yiisoft/http' => 'params',
            
            // Remove groups `params` and `common` from package `yiisoft/view`
            'yiisoft/view' => ['params', 'common'],
        ]),
    ],
);

组合修饰符

Config支持同时使用多个修饰符。

use Yiisoft\Config\Config;
use Yiisoft\Config\ConfigPaths;
use Yiisoft\Config\Modifier\RecursiveMerge;
use Yiisoft\Config\Modifier\RemoveFromVendor;
use Yiisoft\Config\Modifier\ReverseMerge;

$config = new Config(
    new ConfigPaths(dirname(__DIR__)),
    'dev',
    [
        RecursiveMerge::groups('params', 'events', 'events-web', 'events-console'),
        ReverseMerge::groups('events', 'events-web', 'events-console'),
        RemoveFromVendor::keys(
            ['key-for-remove'],
            ['nested', 'key', 'for-remove'],
        ),
    ],
);

命令

yii-config-copy

该插件向Composer添加了额外的yii-config-copy命令。它将包配置文件从供应商复制到根包的配置目录。

composer yii-config-copy <package-name> [target-path] [files]

复制yiisoft/view包的所有配置文件。

# To the `config` directory
composer yii-config-copy yiisoft/view

# To the `config/my/path` directory
composer yii-config-copy yiisoft/view my/path

复制yiisoft/view包中指定的配置文件。

# To the `config` directory
composer yii-config-copy yiisoft/view / params.php web.php

# To the `config/my/path` directory and without the file extension
composer yii-config-copy yiisoft/view my/path params web

为了避免文件名冲突，将在复制的文件名前添加前缀：yiisoft-view-params.php，yiisoft-view-web.php。

yii-config-rebuild

yii-config-rebuild命令更新合并计划文件。如果您已经将文件或目录添加到应用程序配置文件结构中，但这些文件在根包的composer.json中未指定，则可以使用此命令。在这种情况下，您需要通过执行命令将有关新文件的信息添加到根包的composer.json中。

composer yii-config-rebuild

yii-config-info

yii-config-rebuild命令显示应用程序或包的配置详细信息。

composer yii-config-info
composer yii-config-info yiisoft/widget

文档

• 内部

如果您需要帮助或有疑问，Yii论坛是一个很好的地方。您还可以查看其他Yii社区资源。

许可证

Yii Config包是免费软件。它根据BSD许可证的条款发布。有关更多信息，请参阅LICENSE。

由Yii软件维护。

致谢

该插件受到了Composer配置插件的极大启发，该插件最初由HiQDev（https://hiqdev.com/）于2016年创建，然后由Yii采用。

支持项目

关注更新