使用 jbtronics/settings-bundle 的 Symfony 应用程序中的用户可配置设置（部分迁移和环境变量

在本系列的前两部分中，介绍了设置包的基本概念以及如何使用它在 symfony 应用程序中创建良好的用户可配置设置。
在本部分中，您将了解如何对设置进行版本控制并在它们之间进行迁移。此外，您还将学习如何将环境变量与设置结合起来。

版本控制和迁移

随着时间的推移，您的应用程序将会不断发展，您的设置也会不断发展。这意味着随着时间的推移，新参数将添加到设置中，旧参数将被删除，现有参数将被更改。为了解决这个问题，settings-bundle 提供了版本控制和迁移机制，它可以为您处理大部分工作。

假设您有一个像这样的简单设置类：

namespace appsettings;

use jbtronicssettingsbundlesettingssettings;
use jbtronicssettingsbundlesettingssettingsparameter;

#[settings]
class testsettings {

    #[settingsparameter]
    public string $email = 'test@invalid';

    #[settingsparameter]
    public int $baz = 42;
}

这些设置已经在您的应用程序中使用了一段时间，并且用户已经将自定义设置保存到其中。如果您只想向设置添加新参数，只需向类添加新属性即可，这样就可以正常工作。新参数将使用默认值进行初始化，用户可以随意更改：

#[settings]
class testsettings {

    #[settingsparameter]
    public string $email = 'test@invalid';

    #[settingsparameter]
    public int $baz = 42;

    #[settingsparameter]
    public bool $qux = true;
}

删除参数的工作原理类似。如果您从类中删除属性，设置包将忽略它的现有值，并在下次保存设置时将其删除。

但是，更棘手的是，如果您想重命名字段，或者更复杂的是，更改其类型或数据的确切保存方式。为了不丢失用户的现有自定义，您必须指定如何在设置的不同表示形式之间进行转换。设置包可以通过提供迁移框架来支持您。

假设您想要以某种方式更改设置类，以便您现在可以拥有多个电子邮件地址。另外，您想要更改 baz 参数的索引，以便它不是从 0 开始，而是从 1 开始，这意味着所有现有值都应增加 1。最后您的设置类应如下所示：

namespace appsettings;

use jbtronicssettingsbundlesettingssettings;
use jbtronicssettingsbundlesettingssettingsparameter;

#[settings(version: self::version, migrationservice: testsettingsmigration::class)]
class testsettings {

    public const version = 1;

    #[settingsparameter(type: arraytype::class, options: ['type' => stringtype::class])]
    public array $email = ['test@invalid'];

    #[settingsparameter]
    //now with different indexing
    public int $baz = 43;
}

测试设置类现在具有新的预期结构，并且可以在应用程序中使用。但是，settings-bundle 不知道如何将现有数据转换为新结构。这就是迁徙的地方
开始发挥作用。

可以看到settings属性现在指定了version选项和migrationservice选项：

版本选项指定设置的最新模式版本，并且只是一个整数（大于零），每次更改设置类的结构时都会递增。您可以从 1 开始，并在每次更改设置类的结构时递增它。您可以将版本号直接放入属性中，也可以为其定义一个常量，如示例所示，这样做的好处是可以轻松地从类外部检索当前版本。

第二个新东西是migrationservice选项。这指定了实际执行数据迁移的服务类。 migrationservice 必须实现 settingsmigrationinterface，它指定一个 migrate 函数，负责在两个给定的数据版本之间执行迁移。

在大多数情况下，您希望在版本之间逐步迁移（意味着您迁移 1 -> 2，然后迁移 2 -> 3 等等，而不是直接迁移 1 -> 3 以避免代码重复）。在这种情况下，扩展 settingsmigration 类会更容易。使用这个抽象类，您的迁移服务可能如下所示：

namespace appsettingsmigrations;

use jbtronicssettingsbundlemigrationssettingsmigration;

class testsettingsmigration extends settingsmigration  {

    /**
     * this method is called automatically by the migration class and handles 
     * migration of version 0 (non versioned settings) to version 1.
     */
    public function migratetoversion1(array $data, settingsmetadata $metadata): array
    {

        /*
         * $data contains the old settings data, in the normalized form (in the way it was saved in the database)
         * each key is the parameter name (not necessarily the property name) 
         * 
         * in the end we must return the new data in the normalized form, which is later then passed to 
         * the parameter type converters.
         */

        //if the email parameter was set, convert it to an array
        if (isset($data['email'])) {
            $data['email'] = [$data['email']];
        }

        //increment the baz parameter, if it was set
        if (isset($data['baz'])) {
            $data['baz']++;
        }

        //return the new data
        return $data;
    }

    /**
     * this method is called, to handle migration from version 1 to version 2.
     */
    public function migratetoversion2(array $data, settingsmetadata $metadata): array
    {
        //perform some more migrations...

        return $data;
    }

}

迁移服务包含 migratetoversionxx() 形式的各种方法，如果设置从版本 xx-1 迁移到版本 xx，类会自动调用这些方法。该方法接收规范化形式的数据和设置类的元数据，并且必须返回规范化形式的数据，然后将其传递给参数类型转换器。如果您想明确指定哪个版本调用哪些函数，您可以重写resolvestephandler方法，该方法返回要用于给定版本的闭包。

由于现有数据还没有版本，所以假设是版本0。因此，当遇到这些数据settings-bundle时，会调用migratetoversion1处理程序从0迁移到最新版本1。

存储中的旧数据被传递到迁移方法（作为 $data），您必须将其转换为新形式，如何将其保存到存储以及参数类型转换如何理解它。每个参数都存储在 $data 数组中，以参数名称为键。然后您可以根据需要修改数据并最终返回。

请注意，$data 数组是标准化形式，这意味着您只有简单的数据类型，如字符串、整数、数组等。如果您想使用非规范化形式（如对象等），您可能会发现 settingsclass（或 phpvalueconvertertrait）中提供的 getasphpvalue() 和 setasphpvalue() 方法很有用。或者直接调用你需要的parametertype。

settings-bundle 将数据的版本存储在存储提供者中，以便自动获知数据的版本以及要执行的迁移。当尝试检索设置数据时（通过从 settingsmanager 获取设置或调用惰性设置类的属性），会自动执行迁移。默认情况下，迁移后的数据会写回存储，因此每个设置只需执行一次迁移，即使设置没有显式写回存储。

环境变量

环境变量是配置 symfony 应用程序的经典可能性之一。它们允许您通过或多或少统一的界面在自动部署的应用程序、容器等中轻松配置。因此，它们对于希望在不接触代码的情况下配置应用程序的服务器管理员来说非常理想。然而，环境变量的一大缺点是，它们不可由用户配置，因为用户（即使是管理员用户）在不直接访问服务器的情况下无法更改它们。

为了保留环境变量的优点，同时也允许用户通过settings-bundle配置应用程序，bundle可以将环境变量映射到设置类参数。

这是通过 settingsparameter 属性上的 envvar 选项完成的：

#[settings]
class testsettings {

    #[settingsparameter(envvar: 'app_email')]
    public string $email = 'test@invalid';

    #[settingsparameter(envvar: 'int:app_baz', envvarmode: envvarmode::overwrite)]
    public int $baz = 42;

    #[settingsparameter(envvar: 'bool:app_test_settings_qux', envvarmode: envvarmode::overwrite_persist)]
    public bool $qux = true;
}

envvar 选项指定要映射到参数的环境变量。如果它不存在，则什么也不会发生。但是，如果存在，捆绑包将检索环境变量的值并将其设置为参数的值。默认情况下，“raw”环境变量仅包含一个字符串。如果您有另一种简单的数据类型（如整数或布尔值），您可以使用 symfony 的 env var 处理器之一将 env 变量的字符串值转换为所需的类型（例如 int:app_baz，它将 app_baz 的内容转换为到一个整数）。

环境变量处理在后台透明地发生，这意味着您可以照常使用设置类，并且在使用设置时（几乎）不必关心环境变量。

环境变量处理模式

envvarmode 选项指定应如何处理环境变量。如果未指定模式，则使用 e​​nvvarmode::initial 模式。在此模式下，环境变量仅用于初始化参数。这意味着如果第一次使用该参数，则使用环境变量的值，而不是代码中的默认值。用户可以随意更改该值，环境变量不会再影响该参数。此模式允许服务器管理员通过环境变量设置有用的初始默认值（例如，在部署容器时），但用户可以稍后完全更改它们。

但是，在某些情况下，您可能希望服务器管理员通过环境变量强制执行某个值并禁止用户通过 webui 更改它们。对于这些情况，您可以使用 envvarmode::overwrite 和 envvarmode::overwrite_persist 模式。在这种模式下，环境变量将始终覆盖参数值，无论用户之前设置了什么值。这意味着新检索的设置将始终具有环境变量的值，即使用户之前更改了它。 overwrite_persist 模式还会将值写回存储，因此即使在删除 env 变量后该值仍然会被设置（但是用户可以再次更改该值）。

如果参数被环境变量覆盖，其表单字段将在默认生成的 webui 中被禁用，以便用户可以看到该值是由环境变量强制执行的，并且无法通过 webui 更改。

此系统的一个限制是您仍然可以更改代码中设置参数的值，即使它被环境变量覆盖。在请求期间，这些更改还将用于应用程序的其他部分。只是这些更改不会被持久化，这意味着如果您从存储中重新加载设置，则将再次使用环境变量的值。如果您尝试通过代码中的直接访问来更改设置参数，您可能需要检查该参数是否被环境变量覆盖（通过使用 settingsmanager 的 isenvvaroverwriting 方法），如果是这样，您可能需要禁用这种可能性更改代码中的参数。

环境变量映射器

对于许多星座，通过 env var 处理器进行类型转换效果很好。但是，在某些情况下，如果您有更复杂的参数类型，则需要更复杂的转换逻辑。对于这些情况，您可以使用 settingsparameter 属性的 envvarmapper 选项。该选项指定一个可调用的，它使用环境变量的值来调用，并且必须返回该值以设置为参数值：

class TestSettings {

  #[SettingsParameter(envVar: 'string:ENV_VAR3', envVarMapper: [self::class, 'mapDateTimeEnv'])
  private ?DateTime $dateTimeParam = null;

  public static function mapDateTimeEnv(?string $value): ?DateTime
  {
    return $value ? new DateTime($value) : null;
  }
}

传递的 $value 参数是从环境变量检索的值，应用了 env var 处理器，这意味着它不一定是字符串。

结论

您可以看到 jbtronics/settings-bundle 可以支持您处理设置模式中的更改，以及如何将环境变量映射到设置参数。这使您可以拥有灵活的配置系统，可供用户和服务器管理员使用。

一如既往，您可以在捆绑包文档中找到更多信息。