README

是什么？

使用干净的API和易于设置的默认值来设置和检索Craft CMS配置文件值，使其站点感知。

为什么？

当使用多站Craft CMS安装时，您可能会发现自己需要适用于安装中所有站点的配置值，但这些值在站点之间会有所不同。

此插件允许您在站点之间共享模板代码/部分，同时始终获取当前站点（或所需的其他站点）的正确值。

示例用例

API密钥
GA / GTM ID
社交网络链接
资产路径（徽标等）

为什么使用此插件而不是

模板中的逻辑？ 这可以工作，但看起来很丑，而且很快就会变得重复。尽可能让模板只格式化和显示从PHP传递的数据。
Craft全局？ 您可以这样做，但这要快得多（没有数据库/字段开销），更轻量级，并且允许设置默认值以及必要时在站点/站点组之间共享值。
环境变量？ 当可能时，您应该使用环境变量进行配置！但多站安装通常仅靠它们是不够的。您可以在config/siteware.php中（并使用App::env()）设置属于环境的值（如API密钥），这些值可能需要按站点维护。
config/general.php中的自定义密钥？ 对于基本用例，这可以正常工作，但再次设置默认/回退值会很快变得复杂。

如何使用？

此插件使用Craft内置的ConfigHelper::localizedValue()辅助程序来解析config/siteaware.php配置文件中的值，并使它们成为站点感知。然后您可以在模板/PHP代码中消耗它们，而无需担心为正确的站点获取正确的值。

有关配置文件语法，请参阅下面的配置。

要求

此插件需要PHP 7.4+和Craft CMS 3.5或更高版本。它可能（可能）与较旧的Craft版本一起工作，但尚未对其进行测试。

安装

cd /path/to/project
composer require justenoughco/craft-siteawareconfig
./craft plugin/install site-aware-config

配置

编辑config/siteaware.php配置文件以设置您的配置值。

// Craft's multi-environment config syntax is (optionally) supported
    '*' => [
        'staticValue' => 'I am the same for every site',
        'myCustomConfigKey' => [
            // value for the default site
            'default' => 'defaultValue',
            // value for another site
            'aSecondSite' => 'alternateValue',
        ],
        // be careful with nested array values - per site values 
        // are replaced, not merged. e.g. [1] below
        'aDeepNestedKey' => [
            'default' => [
                'apiKey' => 'API_KEY_FOR_DEFAULT_SITE',
                'apiSecret' => 'API_SECRET_FOR_DEFAULT_SITE',
                'deeper' => [
                    'foo' => 'bar',
                    'baz' => 'cux',
                ],
            ],
            // [1] Because we've overwritten aDeepNestedKey for this site,
            // craft.siteAwareConfig.forSite('aSecondSite').aDeepNestedKey.deeper
            // will throw a missing key Error in Twig / UnknownPropertyException
            // in PHP
            'aSecondSite' => [
                'apiKey' => 'API_KEY_FOR_A_SECOND_SITE',
                'apiSecret' => 'API_SECRET_FOR_A_SECOND_SITE',
            ],
        ],
        // Callable example
        'myDynamicKey' => function (string $siteHandle = ''): int {
            return $siteHandle[0] == 'd' ? 1 : 2;
        },
    ],
    // overide a setting in dev environment only
    'dev' => [
        'myCustomConfigKey' => [
            'aSecondSite' => 'aDevOnlyValue',
        ],
        // multi-environment configs are merged, not replaced,
        // so in dev craft.siteAwareConfig.forSite('default').aDeepNestedKey.deeper
        // will work here
        'aDeepNestedKey' => [
            'default' => [
                'apiKey' => 'API_KEY_FOR_DEFAULT_SITE',
            ],
        ],
    ],

检索配置值

模板

当前站点的配置值在Twig下暴露为craft.siteAwareConfig.currentSite

{{ craft.siteAwareConfig.currentSite.perSiteConfigKey }}

如果需要，您可以通过将其句柄传递给craft.siteAwareConfig.forSite()来访问任何站点的配置

{% set defaultSiteConfig = craft.siteAwareConfig.forSite('siteHandle') }}

PHP

暴露给Twig的是justenough\siteawareconfig\services\Config实例。如果您需要，您还可以从PHP领域访问站点感知配置设置

use justenough\siteawareconfig\Plugin as SiteAwareConfigPlugin;

$currentSiteConfig = SiteAwareConfigPlugin::getInstance()->config->config;
$otherSiteConfig = SiteAwareConfigPlugin::getInstance()->config->forSite('siteHandle');

返回的SiteAwareConfig扩展了Yii的BaseObject。

注意事项/潜在“陷阱”

虽然多环境配置中的值被合并，但使用数组语法进行站点感知的值被替换。这通常只有在您使用关联数组作为配置值时才会成为问题（例如，用于将相关值分组在一起）。

如果您需要在站点之间合并值，则可以扁平化您的值或使用可调用项来处理合并/默认逻辑。

归属

由 Just Enough Consulting 提供

图标由 Arthur Shlain 通过 NounProject.com 提供

justenough / craft-siteawareconfig

维护者

详情