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

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

版本控制和迁移

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

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

namespace App\Settings;

use Jbtronics\SettingsBundle\Settings\Settings;
use Jbtronics\SettingsBundle\Settings\SettingsParameter;

#[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 App\Settings;

use Jbtronics\SettingsBundle\Settings\Settings;
use Jbtronics\SettingsBundle\Settings\SettingsParameter;

#[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，它指定一个迁移函数，负责在两个给定的数据版本之间执行迁移。

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

namespace App\Settings\Migrations;

use Jbtronics\SettingsBundle\Migrations\SettingsMigration;

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。

The old data from the storage is passed to the migration method (as $data) and you have to convert it to the new form how it can be saved to storage and how the parameter type conversions can understand it. Each parameter is stored in the $data array with the parameter name as key. You can then modify the data as you like and return it in the end.

Please note that the $data array is in the normalized form, meaning that you only have simple datatypes like strings, integers, arrays and so on. If you want to like to work with the denormalized form (like objects, etc.) you might find the getAsPHPValue() and setAsPHPValue() methods available in the SettingsClass (or in the PHPValueConverterTrait) useful. Or you call the ParameterTypes you need directly.

The settings-bundle stores the version of the data in the storage provider, so that it is automatically known what version the data has and what migrations to perform. The migrations are automatically performed when trying to retrieve settings data (by getting the settings from the SettingsManager or calling a property of a lazy settings class). By default, the migrated data is written back to the storage after the migration, so that the migration only has to be performed once for each setting, even if the settings are not explicitly written back to the storage.

Environment variables

Environment variables are one of the classic possibilities to configure a Symfony application. They allow you for an easy configuration approach in automatic deployed applications, containers, etc. via a more or less unified interface. So they are pretty ideal for server administrators, who want to configure an application without touching the code. However, the big disadvantage of environment variables is, that they are not user-configurable, as users (even those intended as admin users) can not change them without direct access to the server.

To retain the advantages of environment variables, while also allowing users to configure the applications via the settings-bundle, the bundle can map environment variables to settings class parameters.

This is done via the envVar option on the SettingsParameter attribute:

#[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;
}

The envVar option specifies the environment variable to map to the parameter. If it does not exist, nothing happens. However, if it exists, the bundle will retrieve the value of the environment variable and set it as the value of the parameter. By default, the "raw" environment variable contains just a string. If you have another simple data type (like an integer or a boolean), you can use one of Symfony's env var processors to convert the string value of the env variable to the desired type (e.g. int:APP_BAZ, which converts the content of APP_BAZ to an int).

The environment variable handling happens transparently in the background, meaning that you can use the settings class as usual, and you (almost) do not have to care about the environment variables when using the settings.

Environment variable handling modes

The envVarMode option specifies how the environment variable should be handled. If no mode is specified, the mode EnvVarMode::INITIAL is used. In this mode the environment variable is only used to initialize the parameter. That means if the parameter is used the first time, instead of the default value in the code, the value of the environment variable is used. Users can change this value as they like, and the environment variable will not affect the parameter anymore. This mode allows a server administrator to set useful initial defaults via environment variables (e.g. while deploying the container), but users can change them completely later.

However, in some cases, you might want the server admin to enforce a certain value via environment variables and forbid users to change them via WebUI. For these cases, you can use the EnvVarMode::OVERWRITE and EnvVarMode::OVERWRITE_PERSIST mode. In this mode, the environment variable will always overwrite a parameter value, no matter what was set as a value before by users. This means that freshly retrieved settings will always have the value of the environment variable, even if the user changed it before. The OVERWRITE_PERSIST mode additionally writes the value back to the storage, so that the value is still set even after the env variable is removed (however users can then change the value again).

If a parameter is overwritten by an environment variable, its form field will be disabled in the default generated WebUI, so that users can see that the value is enforced by the environment variable and can not be changed via the WebUI.

A limitation of this system is that you can still change the value of a settings parameter in your code, even if it is overwritten by an environment variable. The changes will also be used in other parts of the application during the request. It is just that these changes do not get persisted, meaning that if you reload the settings from the storage, the value of the environment variable will be used again. If you try to change settings parameters via direct access in you code, you might want to check if the parameter is overwritten by an environment variable (by using the isEnvVarOverwritten method of the SettingsManager), and if so, you might want to disable the possibility to change the parameter in your code.

Environment variables mapper

For many constellations, the type conversion via the env var processor works fine. However, in some cases where you have more complex parameter types, you need a more complex conversion logic. For these cases, you can use the envVarMapper option of the SettingsParameter attribute. This option specifies a callable, which is called with the value of the environment variable and must return the value to set as the parameter value:

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;
  }
}

The $value parameter passed, is the value retrieved from the environment variable, with env var processors applied, meaning that it not necessarily has to be a string.

Conclusion

You can see that jbtronics/settings-bundle can support you with handling changes in the schema of settings, and how to map environment variables to settings parameters. This allows you to have a flexible configuration system, which can be used by users and server administrators alike.

As always you can find more information in the bundle documentation.

以上是使用 jbtronics/settings-bundle 的 Symfony 应用程序中的用户可配置设置（部分迁移和环境变量的详细内容。更多信息请关注PHP中文网其他相关文章！