README

Magium 配置管理器 (MCM)

Magium 配置管理器提供了一个类似于 Magento 配置管理的配置设置。此库有 3 个用途

1. 提供一个标准化的配置面板/CLI，这样开发者不需要进行代码部署来更改配置值。
2. 提供一个可继承的接口，其中值可以“冒泡”到子上下文中
3. 为第三方提供一个统一的（读取合并）配置接口，这些第三方在你的应用程序中工作得像神奇独角兽的尘埃。

为了使其为你所用，它需要 3 件事情

1. 一些不同的配置文件（稍后详细介绍）
2. 一个数据库适配器，用于存储持久配置值
3. 一个缓存适配器，用于存储处理过的配置对象

如果你想看到它在行动中的样子，而不是阅读关于它，请查看入门 YouTube 视频。

入门指南

配置连接

核心对象是 ConfigurationRepository 对象。这是你的应用程序通常与之交互的对象。意图是，你只需要引入一个 ConfigurationRepository 对象（或实现 ConfigInterface 的对象）作为依赖项，然后它就会很好地工作。

换句话说，这个

use Magium\Configuration\Config\Repository\ConfigInterface;

class Pinky
{

    protected $brain;
    
    public function __construct(ConfigInterface $brain) 
    {
        $this->brain = $brain;
    }

}

$magiumFactory = new \Magium\Configuration\MagiumConfigurationFactory();
new Pinky($magiumFactory->getConfiguration());

然而，为了使其工作，需要做很多连接工作。幸运的是，如果你想只用我写的，你可以使用它，不必担心编写。MCM 提供了一个配置工厂。它将构建所需的两个类：管理器（为应用程序提供适当的配置对象），以及构建器（构建并填充配置对象）。

配置文件

但在你开始之前，你需要提供至少 3 个（！）配置文件。它们是

1. 全局 magium 配置文件。它包含预设的配置文件、缓存适配器和数据库适配器配置列表。它通常称为 magium-configuration.xml，通常需要放在项目根目录下，最好放在 vendor 目录下方。
2. 上下文配置文件。它包含上下文层次结构。它通常称为 contexts.xml，应位于 magium-configuration.xml 文件中引用的位置。
3. 至少一个实际配置文件。

1 和 2 实际上非常容易开始。你可以手动编写它们，或者可以使用方便的 vendor/bin/magium-configuration CLI 脚本。第一次运行它时，它会询问你将这两个文件放在哪里。

php vendor/bin/magium-configuration
Could not find a magium-configuration.xml file.  Where would you like me to put it?
  [0] C:\Projects\magium-configuration.xml
  [1] C:\Projects\example\magium-configuration.xml
 > 1
Wrote XML configuration file to: C:\Projects\example\magium-configuration.xml
The context file C:\Projects\example\contexts.xml does not exist next to the magium-configuration.xml file.  Create it? y

打开它们并四处看看。

关于 XML 的快速说明。为什么还在使用 XML？它已经过时了！YAML 或 JSON 会让我感觉好得多。

答案是，YAML、JSON或PHP文件都不是自文档化的。我确信有些工具可能允许您执行其中的一些操作，但没有任何工具能与XML可用的工具相提并论。我坚信，当反射用于错误检测或，更重要的是，代码补全时，可以显著减少解决问题所需的时间。它只需要更少的记忆和更少的复制粘贴。但话虽如此，如果您查看/lib目录，您会发现我们的意图是为所有那些受虐狂支持这些格式。

看看magium-configuration.xml文件内部。我相信其中大部分都是自我解释的。然而，请注意persistenceConfiguration和cache节点。这些节点被转换为数组，并分别传递给Zend\Db\Adapter\Adapter和Zend\Cache\StorageFactory类。注意，还有contextConfigurationFile节点。它包含对下一个配置文件的引用。

您的magium-configuration.xml文件可能看起来像这样

<?xml version="1.0" encoding="UTF-8" ?>
<magiumBase xmlns="http://www.magiumlib.com/BaseConfiguration">
    <persistenceConfiguration>
        <driver>pdo_mysql</driver>
        <database>magium_configuration</database>
        <username>root</username>
        <password>password</password>
        <hostname>database</hostname>
    </persistenceConfiguration>
    <contextConfigurationFile file="contexts.xml" type="xml"/>
    <configurationDirectories>
        <directory>config</directory>
    </configurationDirectories>
    <configurationFiles>
        <file>settings.xml</file>
    </configurationFiles>
    <cache>
        <adapter>redis</adapter>
        <options>
            <server>database:6379</server>
        </options>
    </cache>
</magiumBase>

contexts.xml文件不需要叫这个名字；这只是CLI默认创建的。它包含了一个上下文分层列表。每个上下文都必须具有唯一的名称，但它们可以是分层的。

<?xml version="1.0" encoding="UTF-8" ?>
<magiumDefaultContext xmlns="http://www.magiumlib.com/ConfigurationContext">
    <context id="production" title="Production">
        <context id="website1" title="Website 1"/>
        <context id="website2" title="Website 2"/>
    </context>
    <context id="development" title="Development" />
</magiumDefaultContext>

总有一个默认上下文，所有上下文都继承自它。如果您不想使用上下文，只需在其中有<magiumDefaultContext />节点即可。

这种结构允许有覆盖的层次结构。这意味着如果为website1和website2指定了两个不同的值，它们在生成的配置对象中将有不同的值。但是，如果为上下文production提供了值，则除非在那些上下文中覆盖，否则它将存在于website1和website2中。简单而直接。

下一个配置文件是实际设置文件。必须至少有一个，也可以有多个。如果您想的话，甚至可以有一百个。它们都会合并成一个大的元配置XML文件，用于表示检索配置设置的路径。

例如，取两个配置文件

<magiumConfiguration xmlns="http://www.magiumlib.com/Configuration">
    <section identifier="web">
        <group identifier="items">
            <element identifier="element1" />
        </group>
    </section>
</magiumConfiguration>

和

<magiumConfiguration xmlns="http://www.magiumlib.com/Configuration">
    <section identifier="web">
        <group identifier="items">
            <element identifier="element2" />
        </group>
    </section>
</magiumConfiguration>

它们将合并在一起创建

<magiumConfiguration xmlns="http://www.magiumlib.com/Configuration">
    <section identifier="web">
        <group identifier="items">
            <element identifier="element1" />
            <element identifier="element2" />
        </group>
    </section>
</magiumConfiguration>

ID属性用于表示将被查询的实际路径。因此，对于此配置，您可以请求Config对象提供web/items/element1和web/items/element2的值。

您还可以提供默认值和描述

<magiumConfiguration xmlns="http://www.magiumlib.com/Configuration">
    <section identifier="section">
        <group identifier="group">
            <element identifier="element1">
                <description>Just some silly value</description>
                <value>Test Value</value>
            </element>
        </group>
    </section>
</magiumConfiguration>

这只是配置的一小部分。配置可以通过CLI命令使用bin/magium-configuration magium:configuration:set或通过包含的基于Web的视图管理器进行管理。还有其他配置选项可以使该体验更有价值。以下是一个示例，说明这些附加选项可能看起来像什么

<?xml version="1.0" encoding="UTF-8" ?>
<magiumConfiguration xmlns="http://www.magiumlib.com/Configuration">
    <section identifier="website" label="Website" font-awesome="home">
        <group identifier="contact" label="Contact">
            <element identifier="title" label="Title" />
            <element identifier="address" label="Address" type="textarea"/>
            <element identifier="city" label="City" />
            <element identifier="state" label="State" source="Magium\Configuration\Source\Political\USStates" type="select"/>
            <element identifier="phone" label="Phone" type="tel"/>
        </group>
        <group identifier="contact_form" label="Contact Form">
            <element identifier="title" label="Title" />
            <element identifier="sendto" label="Send To" type="email"/>
            <element identifier="permitted" type="select">
                <permittedValues>
                    <value>yes</value>
                    <value>no</value>
                </permittedValues>
            </element>
        </group>
    </section>
</magiumConfiguration>

/website显示label和font-awesome属性，这提供了更友好的配置交互。font-awesome（以及glyphicon）属性用来自这两个集合之一的图标装饰该部分。

在元素方面，查看website/contact/address，您可以看到有不同类型的表单字段可用。它们是

• 多选
• 选择
• 文本
• 多行文本框
• 网址
• 电话
• 电子邮件
• 日期（用于将来使用）
• 日期时间（用于将来使用）

您还可以看到，当查看website/contact/state时，个别元素可以从源中填充。这些源可以用于预先填充文本字段或提供选择选项。请参阅源代码以获取完整列表。

环境变量覆盖

您还可以通过使用环境变量来覆盖您的 magium-configuration.xml 文件中的值。这允许您根据运行的环境更改基本设置，例如本地缓存适配器的主机名。例如，您的开发环境可能有一个位于 localhost 的 Redis 适配器，但在生产环境中它位于 cache.myhost。要处理这种情况，请将 cache/options/server 的值设置为 cache.myhost（默认为生产环境）。然后在您的 开发 环境中将以下内容添加到您的 web 服务器配置（或类似配置）中

location ~ \.php$ {
    fastcgi_pass     unix:/your_sock_location/nginxFastCGI.sock;
    fastcgi_param    SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param    MCM_CACHE_OPTIONS_SERVER=localhost;
    include          fastcgi_params;
}

magium-configuration.xml 文件中的任何值都可以被覆盖，并可以通过创建以 MCM_ 为前缀的变量并用您想要更改的节点路径附加到节点来替换环境变量。

例如，查看我们上面所做的，这是针对配置节点 cache/options/server 的，所以我们命名我们的环境变量为 MCM_CACHE_OPTIONS_SERVER。

配置您的应用程序

如果您打算使用包中包含的基本工厂，那么连接 MCM 比较简单。

$factory = new \Magium\Configuration\MagiumConfigurationFactory();
$config = $factory->getManager()->getConfiguration(getenv('ENVIRONMENT'));

就是这样。然后，无论您在哪里使用该配置对象（假设您正在使用之前的 XML 文件），检索配置值就像这样

echo config->getValue('web/items/element1');

更多示例，包括原始示例和针对各种框架的示例，可以在 配置管理器示例 页面上找到。

设置配置值

配置值通过使用 vendor/bin/magium-configuration 脚本并使用 magium:configuration:set 命令通过命令行设置。

例如，考虑到之前的配置文件，您可以通过调用以下方式设置值

php vendor/bin/magium-configuration magium:configuration:set section/group/element1 "some value"

然后当您调用

$config->getValue('web/items/element1')

您将获得配置的值。

此外，如果您想为特定上下文设置值，请将其附加到 set 命令的末尾

php vendor/bin/magium-configuration magium:configuration:set section/group/element1 "some value" website1

就这样。

第三方集成

如果您正在构建任何需要连接到 MCM 的第三方模块，最简单的方法是通过 Magium\Configuration\File\Configuration\ConfigurationFileRepository 连接。它在构建配置对象之前使用，在将其存储在缓存中之前。通过 Composer 自动加载器来完成此操作。

{
    "autoload": {
        "files": [
            "registration.php"
        ]
    }
}

composer.json

$instance = \Magium\Configuration\File\Configuration\ConfigurationFileRepository::getInstance();
$instance->addSecureBase(realpath('etc'));
$instance->registerConfigurationFile(
    new \Magium\Configuration\File\Configuration\XmlFile(
        realpath(
            'etc/settings.xml'
        )
    )
);

registration.php

您的配置设置现在已包含在您的客户的应用程序中。请注意，但是，您不应该有一个 magium-configuration.xml 文件或您自己的上下文文件。这是主要应用程序管理的。

前进方向

以下是我希望包含的功能列表

• 一个基于 HTML 的 UI，用于进行配置更改
  • 可嵌入的用户限制
  • ACL 资源
• 一个本地/远程缓存系统，它在本地上缓存配置，但与远程缓存同步
• 与多个第三方依赖注入容器的集成/适配器，允许您集中管理 DI 配置，以及/或者在不要求部署的情况下动态修改 DI 配置。（某种程度上）
• 是的，还有与持久存储的集成