README

安装

TYPO3配置处理仅适用于启用composer的（Composer模式）TYPO3项目。

1. 运行 composer req helhum/typo3-config-handling

免责声明

在开始使用此包之前，您应该了解以下内容

1. 为了实现最佳性能和便利性，此包覆盖了TYPO3类 TYPO3\CMS\Core\Configuration\ConfigurationManager。与其他包中类的覆盖一样，这带来了一些缺点，最突出的是，当使用此包时，上游包中引入的修复程序不会自动应用。如果您不愿意接受这种缺点，您应避免使用此包。
2. 为了在生产环境中实现最佳性能，此包将配置值缓存在单个文件中。这意味着，当您在开发过程中将 TYPO3_CONTEXT 设置为 Production 时运行您的TYPO3应用程序，手动更改配置文件会影响缓存。然而，当使用任何TYPO3 UI（安装工具）更改配置值时，缓存将自动刷新。为了避免麻烦，建议在您的开发环境中将 TYPO3_CONTEXT 设置为 Development。

功能

环境依赖的设置

根据TYPO3运行的环境（哪个服务器），一些设置需要更改以匹配此环境。例如，数据库连接设置、指向外部工具（如Graphicsmagick）的路径或邮件投递设置。TYPO3配置处理允许您在多个文件中分发您的TYPO3设置，并从环境变量、其他配置值和常量中拉取配置值。

其他格式的配置文件

TYPO3仅允许在两个PHP文件 LocalConfiguration.php 和 AdditionalConfiguration.php 中提供设置。当使用此包时，可以提供Yaml格式的TYPO3设置（理论上可以在任何可以解析为数组的格式中提供，但当前仅实现了Yaml）。使用较新的TYPO3版本，Yaml格式已用于多个方面，如表单定义、RTE配置或站点配置。使用TYPO3配置处理，也可以以Yaml格式提供系统设置。

存储在 config 文件夹中的配置文件

TYPO3将配置文件存储在文档根目录中。当使用TYPO3配置处理时，配置文件将存储在 config 文件夹中，与TYPO3站点配置文件一起。

增强的站点配置

TYPO3 9.5引入了站点的概念。站点配置在存储在 config/sites/<site-identifier>/config.yaml 的yaml文件中。这个很好的概念有一些小的限制，可以通过使用此包来克服。

1. yaml文件的缩进为2个空格，这使得阅读它们变得困难。现在在重新编写配置文件时使用4个空格已更改。

2. 虽然可以使用导入功能导入其他文件，但导入功能限制为从扩展或相对于TYPO3主目录（PATH_site）导入文件。通过使用更高级的当前配置文件相对导入处理来解决这个问题。

3. TYPO3 默认仅支持 env 占位符替换，这意味着环境相关的网站配置必须使用环境变量。为了克服这一限制，使用本包可以在常规主配置中覆盖网站配置。

   Site:
        site-identifier:
            base: 'https://overridden.tld' 

   这样就可以将所有环境特定的配置放入 override.settings.yaml 中，而无需在环境中暴露某些设置。

要启用此功能，需要在主配置中注册一个 XCLASS。

SYS:
    Objects:
        TYPO3\CMS\Core\Configuration\SiteConfiguration:
            className: Helhum\TYPO3\ConfigHandling\Typo3SiteConfiguration

在配置文件中加密值

凭证不应放入版本控制。为了实现这一点，可以将凭证放在环境变量或相应系统上的 overrides.settings.yaml 中。然而，这可能会根据目标系统的设置变得繁琐。本包提供了一个折衷方案。凭证使用强加密加密，然后放入版本控制。然后只需在目标环境中一次性提供加密密钥。如果这样做，可以通过将其添加到版本控制来随着时间的推移添加新的加密值。

要在一个配置文件中加密值，可以使用命令行命令 typo3cms settings:encrypt -c config/live.yaml。如果未向此命令提供加密密钥，则将生成一个新的加密密钥并在输出中显示。

然后将此加密密钥一次性放入目标系统上的 override.settings.yaml。

SYS:
    settingsEncryptionKey: def000008a...

通过这种方式，所有遵循 %decrypt(<encryptedString>)% 语法的值将在运行时解密，并以明文值的形式呈现给 TYPO3。

settings:encrypt 命令行命令在以下格式中查找配置值：%encrypt(<value to encrypt>)%

从这样的占位符中提取值，使用给定的加密密钥加密，并用 %decrypt(<encryptedString>)% 替换。

如果您想使用此功能，需要遵循一些先决条件

• 需要在项目中安装 composer 包 defuse/php-encryption。

• 需要将解密处理器添加到配置文件之一。

  processors:
      decrypt:
          class: Helhum\TYPO3\ConfigHandling\Processor\DecryptSettingsProcessor

如您所见，解密完全基于处理器，该处理器处理占位符。因此，可以实现自己的处理器，该处理器从目标环境中的凭证存储中检索凭证。例如，您可以有如下占位符 %encrypt(my-database-password)%，处理器代码可以通过使用标识符 my-database-password 在保险库中查找凭证。

在未来版本中，本包可能会支持一些这些保险库，或者第三方包可以提供对这种凭证存储的支持源。

将 TYPO3 项目迁移到使用 TYPO3 配置处理

1. 安装 包使用 composer
2. 运行 vendor/bin/typo3cms settings:extract --config-file config/settings.yaml 从现有的 LocalConfiguration.php 文件中提取配置值

多个设置文件

占位符

在配置值中，支持各种占位符，包括环境变量、其他配置值和 PHP 常量

%env(TYPO3_PATH_COMPOSER_ROOT)%

%conf(EXTCONF.filefill.reverseProxyCookie)%

%const(TYPO3\CMS\Core\Log\LogLevel::EMERGENCY)%
%const(TYPO3_CONTEXT)%

更改配置目录布局

将以下部分添加到您的 composer.json 中，以更改配置目录结构以适应您的需求。请注意，您只需指定两个上下文中的入口点配置，并在这些文件中可以指定后续配置文件的导入。

可选地，对于自动 LocalConfiguration.php 配置提取，可以指定用于提取主配置和扩展配置的不同文件。

所有路径相对于您的根 composer.json 目录，并且不能以斜杠开头。

默认布局

{
    "extra": {
        "helhum/typo3-config-handling": {
            "settings": "config/settings.yaml",
            "dev-settings": "config/dev.settings.yaml",
            "override-settings": "config/override.settings.yaml",
            "install-steps": "config/setup/install.steps.yaml"
        }
    }
}

示例以匹配 Symfony 框架默认布局

{
    "extra": {
        "helhum/typo3-config-handling": {
            "settings": "config/config_prod.yaml",
            "dev-settings": "config/config_dev.yaml"
        }
    }
}

示例以匹配 Neos Flow 框架风格布局

{
    "extra": {
        "helhum/typo3-config-handling": {
            "settings": "Configuration/Settings.yaml",
            "dev-settings": "Configuration/Development/Settings.yaml"
        }
    }
}