DEV Community: Jan Böhmer

User-configurable settings in Symfony applications with jbtronics/settings-bundle (Part 3): Migrations and environment variables

Jan Böhmer — Wed, 17 Jul 2024 07:55:10 +0000

In the first two parts of this series, the basic concepts of the settings-bundle were introduced and how to use it to create nice user-configurable settings in Symfony applications.
In this part, you will learn how to version your settings and migrate between them. Additionally, you will learn how to combine environment variables with settings.

Versioning and migration

Over time you application will evolve and so will your settings. This means that over time new parameters will be added to settings, old ones will be removed and existing ones will be changed. To handle this, the settings-bundle provides a versioning and migration mechanism, which takes care of most of the work for you.

Let's assume you have a simple settings class like this:


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

These settings were already used for some time in your application and users already saved their customizations to it. If you just want to add a new parameter to the settings, you can do this by simply adding a new property to the class, and it will work fine. The new parameter will be initialized with the default value and users can change it as they like:


#[Settings]
class TestSettings {

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

    #[SettingsParameter]
    public int $baz = 42;

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

Removing a parameter works similarly. If you remove a property from the class, the settings-bundle will ignore existing values for it, and delete it the next time the settings are saved.

However, what is more tricky, is if you want to rename a field or, even more complex, change its type or how data is exactly saved. To not lose existing customizations of users, you have to specify how to convert between the different representations of the settings. The settings-bundle can support you with this by providing a framework for migrations.

Let's assume you want to change your settings class in a way, that you now can have multiple email addresses. Also, you want to change the indexing of the baz parameter, so that it not start at 0, but at 1, meaning that all existing values should be incremented by 1. In the end your settings class should look like this:


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

The test settings class now have the new intended structure and can be used in the application. However, the settings-bundle will not know how to convert the existing data to the new structure. This is where migrations
come into play.

You can see that the settings attribute now have the version option and the migrationService option specified:

The version option specifies the most recent schema version of the settings and is just a integer (greater zero), which is incremented every time you change the structure of the settings class. You can start with 1 and increment it every time you change the structure of the settings class. You can put the version number directly into the attribute, or you can define a constant for it, as shown in the example, which has the advantage that you can retrieve the current version easily from outside the class.

The second new thing is the migrationService option. This specifies the service class, which actually performs the data migration. The migrationService must implement the SettingsMigrationInterface, which specifies a migrate function that is responsible for performing migration between two given versions of the data.

In most cases you want to step-wise migrations between the versions (meaning you migrate 1 -> 2, then 2 -> 3 and so on, instead of 1 -> 3 directly to avoid code duplication). In this situation, it is easier to extend the SettingsMigration class. Using this abstract class, your migration service might look like this:


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

}

The migration service contains various methods in the form migrateToVersionXX(), which are called automatically by the class if the settings are migrated from version XX-1 to version XX. The method receives the data in the normalized form and the metadata of the settings class and must return the data in the normalized form, which is then passed to the parameter type converters. If you want to specify explicitly which functions are called for which version, you can override the resolveStepHandler method, which returns the closure to use for a given version.

As the existing data had no version yet, it is assumed it was version 0. Therefore, when encountering these data settings-bundle will call the migrateToVersion1 handler to migrate from 0 to the most recent version 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.

User-configurable settings in Symfony applications with jbtronics/settings-bundle (Part 2): Forms

Jan Böhmer — Thu, 02 May 2024 12:09:45 +0000

After the first blog post of this series explained the basic concepts of the settings-bundle, this blog post will show how to use jbtronics/settings-bundle to create WebUI forms
to change the settings.

Creating forms for settings

Remember the appearance settings from the last blog post? We will now create a form to change these settings:


<?php
// src/Settings/AppearanceSettings.php

namespace App\Settings;

use Jbtronics\SettingsBundle\Settings\Settings;
use Jbtronics\SettingsBundle\Settings\SettingsParameter;
use Jbtronics\SettingsBundle\Storage\JSONFileStorageAdapter;
use Jbtronics\SettingsBundle\Settings\SettingsTrait;
use Symfony\Component\Validator\Constraints as Assert;

#[Settings(storageAdapter: JSONFileStorageAdapter::class)]
class AppearanceSettings {

    #[SettingsParameter]
    #[Assert\Language]
    public string $language = 'en';

    #[SettingsParameter]
    public bool $darkMode = false;

    #[SettingsParameter]
    #[Assert\Range(min: 12, max: 24)]
    public int $fontSize = 16;

    #[SettingsParameter()]
    public MyTheme $theme = MyTheme::MODERN;
}

To create forms for settings, you can use the SettingsFormFactoryInterface service. Its createSettingsFormBuilder() method takes a settings instance and returns a form builder, containing a form field for each settings parameter. As it is still a form builder you can add your own additional fields or modify the form as you like. For example, you probably want to add a submit button, so that the user can save the settings:

<?php
// src/Controller/SettingsController.php

namespace App\Controller;

use App\Settings\AppearanceSettings;
use Jbtronics\SettingsBundle\Form\SettingsFormFactoryInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class SettingsController extends AbstractController
{
    public function __construct(
        private SettingsFormFactoryInterface $settingsFormFactory,
        private SettingsManager $settingsManager)
    {
    }

    public function appearance(Request $request, AppearanceSettings $settings)
    {
        //Create a builder for the settings form
        $builder = $settingsFormFactory->createSettingsFormBuilder($settings)->getForm();

        //Modify the form: Add a submit button, so we can save the form
        $builder->add('submit', SubmitType::class);

        $form = $builder->getForm();
        $form->handleRequest($request);

        //If the form is submitted and valid, save the settings
        if ($form->isSubmitted() && $form->isValid()) {
            $settingsManager->save($settings);
        }

        return $this->render('settings/appearance.html.twig', [
            'form' => $form->createView(),
        ]);
    }
}

The settings instance is bound to the form so that the form fields are prefilled with the current settings and changes to the form are reflected in the settings instance. If the form was submitted you then just need to call the save() method of the SettingsManager to save the settings to the storage. However this approach of directly using the global settings instance in the controller has it disadvantages, which will be discussed (and solved) later. For now we will just use this approach to keep things simple.

Customizing the form

If you write a twig template, which renders the form and view the result, you will notice that for the $darkMode parameter a Checkbox was chosen, and for the $fontSize parameter a NumberType input field was chosen. This is because settings-bundle detected the type of the parameter based on the property type hint and assigned the BoolType and IntType parameter types to these parameters. These parameter types are not only used to convert the property values to a storable format and vice versa, but they can also make presets for the rendering of the form fields. Not every parameter type needs to do that, but at least the built-in parameters try to make a good assumption of what form type and what form options to use, to get a nice-looking form, without much customizing.

However, in some cases the presets are not what you want and you might want to change the form type and/or form options. You can do this by utilizing the formType and formOptions options on the SettingsParameter attribute:

#[SettingsParameter(formType: LanguageType::class, formOptions: ['choice_self_translation' => true])]
#[Assert\Language]
public string $language = 'en';

If you want to specify the form label and a description of the form field (which will be shown as help text), you can use the label and description options of the attribute.
This also has the advantage, that this allows to utilize this information in other contexts, too.

#[SettingsParameter(label: "Font size", description: "The font size in pixels to use (between 12 and 24)")]
#[Assert\Range(min: 12, max: 24)]
public int $fontSize = 16;

The strings given there are passed to Symfony form component like normal, meaning that these keys also get translated if you use the translator service.

Forms for multiple settings and embedded settings

If you have multiple settings classes, you wanna create a common form for them, you can use the createMultiSettingsFormBuilder() method of the SettingsFormFactoryInterface service,
which takes an array of settings instances and returns a form builder subforms for each settings instance. This sub-form builder then contains a form field for each settings parameter of each settings instance.

However, for more complex setting structures you might want to use a hierarchical organization of settings. This can be achieved by using so-called settings embeds. If you have a settings class you can add a property to it and mark it with the #[EmbeddedSettings] attribute. The settings-bundle will then fill this property with the instance of the other settings class so that you can access the settings of the embedded settings class through the parent settings class. This is useful if you have settings that are only relevant in a certain context or if you want to group settings. If you worry about performance, do not worry. The injecting embedded settings are lazy-loaded, so that they only get initialized when you access them.

<?php

namespace App\Settings;

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

#[Settings]
class AppSettings {

        #[SettingsParameter]
        public string $appName = 'My App';

        #[SettingsParameter]
        public string $appVersion = '1.0.0';

        //The instance of the AppearanceSettings class will be injected here by the settings-bundle
        #[EmbeddedSettings]
        public AppearanceSettings $appearanceSettings;

    }

Settings-bundle will automatically detect the class to inject based on the property type hint. If you want to specify the class to inject, you can use the target option of the EmbeddedSettings attribute, but normally everything should be automatically detected. The embedded settings are the same instance as the global settings object, so you can read and modify the settings of the embedded settings class in the same way as the global settings object.

There is no limit on how deep you can nest embedded settings, so you can create complex settings structures with multiple levels of embedded settings. However, you should be careful with this, as it can make the settings structure hard to understand and maintain. But this also allows you to split up your settings for various parts of your application in a way, that each service only gets the settings it requires, while you can still have a common settings object which contains all settings, for easy access and modification by users.

In principle, settings-bundle can even handle circular embedded settings (A embeds B, B embeds A), but you should avoid this, as you can not easily convert such structures to forms.

The methods of the SettingsManager, normally affect the whole cascade of settings, so if you call save(), reload(), etc. on the top level settings object, it will also affect all embedded settings. You can control this behavior via the cascade parameter of the methods of the SettingsManager. If you set it to false, the method will only affect the settings object you called the method on.

If you call the createSettingsFormBuilder method on a settings object with embedded settings, the return form builder will contain the nested structure of the settings. For each embedded settings object, a subform will be created, allowing you to easily create forms for complex settings structures.

Only showing a subset of settings in a form

Maybe you sometimes want to only show some settings parameters in a form, not all. For example, if you wanna offer a "simple" settings form, where more advanced settings are hidden.
You can achieve this by using the groups option on the #[SettingsParameter] (and #[EmbeddedSettings]) attributes. These groups work very similar to the groups of the symfony/serializer group. You can specify a list of groups a parameter belongs to and then you can specify the groups you want to include in the form builder. On #[Settings] attribute you can specify the default groups for a settings class when it has no explicitly specified groups.

<?php

namespace App\Settings;

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

#[Settings(groups: ['simple', 'advanced'])]
class SecuritySettings {
    #[SettingsParameter(groups: ["advanced"])] //Override the default groups of the settings class
    public string $secret = 'mysecret';

    #[SettingsParameter(groups: ["simple", "advanced"])]
    public bool $enforce2FA = false;

    #[SettingsParameter] //This parameter will be in the "simple" and "advanced" group, as inherited from default
    public bool $limitLoginAttempts = true;
}

If you now call the createSettingsFormBuilder with the groups option, to specify which groups should be included. By default (if the value is null), then all groups are included.


$settings = $this->settingsManager->get(SecuritySettings::class);

//This form builder includes all parameters of the SecuritySettings class
$builder = $settingsFormFactory->createSettingsFormBuilder($settings);

//This form builder only includes the parameters of the "simple" group
//Therefore the "secret" parameter is not included
$builder = $settingsFormFactory->createSettingsFormBuilder($settings, ['simple']);

The groups option is an OR condition, so a parameter is shown if it is in at least one of the specified groups. Embedded settings are also only shown if they are in at least one of the specified groups (you can specify the groups of embedded settings in the same way as for normal settings).

Working with temporary copies of settings

One big problem here is how Symfony Forms work: They apply the changes directly to the object you pass to them and do the validation afterward. And even if the validation fails, the changes are still there in the object for the remainder of the request. This is a problem if other parts of your application depend on the settings object, as they will see the changes,
even if the validation failed. Depending on your application, invalid values can cause undesired behavior or exceptions.

To fix this problem, you can retrieve a temporary copy of a settings object, which is completely independent of the global settings object. Therefore the form can modify it as it wants
without affecting the global settings object with invalid values. You can create it by calling the createTemporaryCopy() method on the SettingsManager service. The settings manager creates a new instance and copies all parameter values over to it. If you have embedded settings, the embedded settings are also copied, so that you get a complete deep copy of the settings object, containing the old values.

To save the changes to storage, you first need to merge the temporary copy back to the global settings object. This can be done by calling the mergeTemporaryCopy() method on the SettingsManager service. It will be verified that the temporary copy is valid and otherwise an exception is thrown so that no invalid data can be merged back. All parameter values of the temporary copy are then copied back to the global settings object so that the changes can be saved to storage. If you have embedded settings, the embedded settings are also merged back by default, you can control this behavior with the cascade option, however.

<?php
// src/Controller/SettingsController.php

namespace App\Controller;

use App\Settings\AppearanceSettings;
use Jbtronics\SettingsBundle\Form\SettingsFormFactoryInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class SettingsController extends AbstractController
{
    public function __construct(
        private SettingsFormFactoryInterface $settingsFormFactory,
        private SettingsManager $settingsManager)
    {
    }

    public function appearance(Request $request)
    {
        //Create a temporary copy of the settings
        $clone = $settingsManager->createTemporaryCopy(AppearanceSettings::class);

        //Create a builder for the settings form
        $builder = $settingsFormFactory->createSettingsFormBuilder($clone)->getForm();

        //Modify the form: Add a submit button, so we can save the form
        $builder->add('submit', SubmitType::class);

        $form = $builder->getForm();
        $form->handleRequest($request);

        //If the form is submitted and valid, save the settings
        if ($form->isSubmitted() && $form->isValid()) {
            //Merge the temporary copy back to the global settings object, so that we can save the changes
            $settingsManager->mergeTemporaryCopy($clone);
            $settingsManager->save();
        }

        return $this->render('settings/appearance.html.twig', [
            'form' => $form->createView(),
        ]);
    }
}

If you do not use "simple" data types like strings, bools, enums, etc. as settings parameters, but more complex objects, which are not easily cloneable, you maybe need to implement
some custom copy and merge behavior for the settings object. You can do this by implementing the CloneAndMergeAwareSettingsInterface interface on your settings class. See the documentation for more information.

Conclusion

You can see that jbtronics/settings-bundle allows you to easily build settings forms, even for complex use cases. You can find more information about form generation and some more
advanced things, like how to implement your own settings parameter types with form presets, in the documentation.

There you can also already find the documentation about more advanced features like settings versioning/migrations and how to combine settings with environment variables for easy automatic deployment of your application. That will be the topic of the next blog post of this series.

User-configurable settings in Symfony applications with jbtronics/settings-bundle (Part 1)

Jan Böhmer — Mon, 08 Apr 2024 09:57:31 +0000

Symfony offers vast configuration possibilities using container parameters and environment variables. However, these are only useful for configuration intended to be configured by developers, as they require changing various text files on the server and might even some recompilation of the container (by running a cache:clear command).
If you want to allow end-users to configure various aspects of an application, they will need some kind of WebUI to do so (like, for example, WordPress does). However, there is no good way to change Symfony's container parameters or env variables (from various sources) from inside a Symfony application itself.

For this reason, if you want to have user-configurable settings you have to store and work with them independently. For this there are already several Symfony bundles, with the most popular being probably sherlockode/configuration-bundle. However all of these bundles are more or less a simple key-value store, where a configuration can be retrieved via something like $parameterManager->get('contact_email'). However this is not really type-safe and DX-friendly, as the return type of the get method is not obvious and you have to check yourself which keys are available and auto-complete in common IDEs is not possible.

Class-based settings

To solve these problems, the MIT-licensed jbtronics/settings-bundle was created. The basic idea is that settings parameters are not organized in a simple key-value storage, but are based around classes. Each (settings) class represents a set of parameters, which are somehow logically connected.

After you have installed the bundle with composer (composer require jbtronics/settings-bundle), you can create a new settings class in the src/Settings directory of your symfony application.

For example, if you want to allow users to configure the appearance settings of your application, you might create a AppearanceSettings class like this:

<?php
// src/Settings/AppearanceSettings.php

namespace App\Settings;

use Jbtronics\SettingsBundle\Settings\Settings;
use Jbtronics\SettingsBundle\Settings\SettingsParameter;
use Jbtronics\SettingsBundle\Storage\JSONFileStorageAdapter;
use Jbtronics\SettingsBundle\Settings\SettingsTrait;
use Symfony\Component\Validator\Constraints as Assert;

#[Settings(storageAdapter: JSONFileStorageAdapter::class)]
class AppearanceSettings {

    #[SettingsParameter]
    #[Assert\Language]
    public string $language = 'en';

    #[SettingsParameter]
    public bool $darkMode = false;

    #[SettingsParameter]
    #[Assert\Range(min: 12, max: 24)]
    public int $fontSize = 16;

    #[SettingsParameter()]
    public MyTheme $theme = MyTheme::MODERN;
}

where MyTheme is an enum class like this:

<?php

namespace App\Settings;

use Jbtronics\SettingsBundle\Settings\Enum;

enum MyTheme: string {
    case MODERN = 'modern';
    case TRADITIONAL = 'traditional';
    case FANCY = 'fancy';
}

As you can see, the AppearanceSettings class is a normal PHP class with some properties. They do not even need to be public, you could also define some getter/setter methods to access them. But we omit that here to make the example more concise.

The only thing special about this class, are the attributes #[Settings] and #[SettingsParameter]. The #[Settings] attribute marks this class as a settings class, which means that it will be automatically registered with the bundle. The storageAdapter attribute specified, which storage backend will be saved to actually store the settings. There are multiple storage adapters available, for saving settings in files in various formats or a database. For simplicity, we will use the JSONFileStorageAdapter here, which will save the settings in a JSON file in the var/settings directory of your Symfony application.

The #[SettingsParameter] attribute marks a property as a settings parameter, which means that it will be saved and loaded by the bundle. If you retrieve an instance of the AppearanceSettings via the bundle, then these properties are automatically filled with the values from the storage backend.

As many more complex datatypes (objects, etc.) can not be directly saved to the storage backend, the PHP data is normalized/denormalized by so-called ParameterTypes, which you can set as an option in the SettingsParameter attribute. However, for elementary types like string, int, bool, etc., and even for enums, the correct parameter type is automatically detected by the bundle, based on the type declaration of the property and you don't need to specify it manually.

If you have a more complex datatype, like a custom object, you can easily create your own ParameterType class, which implements the ParameterTypeInterface and then specify it in the SettingsParameter attribute, so that the bundle knows how to normalize/denormalize this datatype.

Getting current settings

If you wanna read the configured value of a parameter, you can do it by directly accessing the property (or the getter) of the settings object. However, you can not just do a new AppearanceSettings(), as this would create a new instance of the class with the default values. Instead, you need to retrieve a settings object from the bundle.

However as the bundle registers all settings classes as services by default, you can simply inject the settings class as a dependency in your controller or service. The bundle will automatically load the settings from the storage and fill the properties of the object with the data. If no settings are found in the storage, then the default values of the properties are used.

<?php 
namespace App\Controller;

use App\Settings\AppearanceSettings;

class MyController extends AbstractController {

    public function index(AppearanceSettings $appearanceSettings) {
        // $appearanceSettings is already filled with the data from the storage
        // To read the values, you can simply access the properties/fields of the object
        $language = $appearanceSettings->language;
        $darkMode = $appearanceSettings->darkMode;
        $fontSize = $appearanceSettings->fontSize;
        $theme = $appearanceSettings->theme;
    }
}

The cool thing is, that the properties are type-hinted, so you get auto-completion in your IDE and you can be sure that the value is of the correct type. If you try to set a value of the wrong type, you will get an exception. Also if you retrieve the settings object like this then you have no direct dependency on the settings bundle and you can easily replace the settings instance with a mock in your tests.

If you worry about the performance of loading the settings from the storage every time your services get initialized, you do not have to. The bundle actually replaces the settings object with a lazy proxy, which only really loads the settings from the storage when data is actually accessed. So if your code never actually requires some settings data, then the settings are never loaded from the storage too.

If you want to use settings in a twig template, you can either pass the settings object to the template or you can use the settings_instance twig function defined by the bundle. This function returns the settings object of a given class, which you can then use in your template. The function expects either the fully qualified class name of the settings class, which is not so easy to type in twig, or the so-called short Name of the class. This is by default the class name without the namespace, but you can also specify a custom short name for a settings class by using the shortName attribute of the Settings attribute.

{# @var settings \App\Settings\AppearanceSettings #}
{% set settings = settings_instance('\\App\\Settings\\AppearanceSettings') %}
{{ dump(settings) }}

{# or directly #}
{{ settings_instance('appearance').language }}

Changing settings

To change the value of a settings parameter, you can simply set the property of the settings or use any setter method you have defined:

<?php
namespace App\Controller;

use App\Settings\AppearanceSettings;

class MyController extends AbstractController {

    public function changeSettings(AppearanceSettings $appearanceSettings) {
        $appearanceSettings->language = 'de';
        $appearanceSettings->darkMode = true;
        $appearanceSettings->fontSize = 18;
        $appearanceSettings->theme = MyTheme::FANCY;
    }
}

All services share the same instance of the settings object, so if you change a value in one service or controller, then it will directly be reflected in all other services and controllers.
So as long as your code always accesses the property or getter of the settings object directly and does not cache the value in a local variable, you can be sure that always the current value is used.

However, this only affects the instance of the settings object in the current request. If you want to persist the changes to the storage, you have to explicitly save the settings object.

Persisting changes

If you want to interact explicitly with the bundle, then you can use the SettingsManagerInterface service. This service allows you to retrieve, save, and reset settings objects.

<?php
namespace App\Controller;

use App\Settings\AppearanceSettings;
use Jbtronics\SettingsBundle\Manager\SettingsManagerInterface;

class MyController extends AbstractController {

    public function changeSettings(SettingsManagerInterface $settingsManager) {
        //Instead of dependency injection, you can also use the get method of the settings manager to retrieve the settings instance
        $appearanceSettings = $settingsManager->get(AppearanceSettings::class);

        // Change the settings
        $appearanceSettings->language = 'de';
        $appearanceSettings->darkMode = true;
        $appearanceSettings->fontSize = 18;
        $appearanceSettings->theme = MyTheme::FANCY;

        // Persist the settings to storage
        $settingsManager->save($appearanceSettings);
    }
}

Before writing the settings to the storage, the bundle will also validate the settings object, using the Symfony validator component. If the settings object is not valid, according to the defined constraints, then an exception is thrown and the settings are not saved.

If you somehow end up in a situation where you want to discard the changes you made to the settings object, you can simply call the reload method of the SettingsManagerInterface service, which will reload the settings from the storage and discard all changes you made to the object. Only the parameter properties of the object are reset, the instance itself is not replaced, so that all references to the object in some other places of your code are still valid.

<?php
namespace App\Controller;

use App\Settings\AppearanceSettings;
use Jbtronics\SettingsBundle\Manager\SettingsManagerInterface;

class MyController extends AbstractController {

    public function changeSettings(SettingsManagerInterface $settingsManager) {
        $appearanceSettings = $settingsManager->get(AppearanceSettings::class);

        // Change the settings
        $appearanceSettings->language = 'de';
        $appearanceSettings->darkMode = true;
        $appearanceSettings->fontSize = 18;
        $appearanceSettings->theme = MyTheme::FANCY;

        // Discard the changes
        $settingsManager->reload($appearanceSettings);
    }
}

If you want to reset the settings to their default values, defined in the code, you can use the resetToDefaultValues method of the SettingsManagerInterface service. Like the reload method, this method will also maintain the instance of the settings object.

<?php
namespace App\Controller;

use App\Settings\AppearanceSettings;
use Jbtronics\SettingsBundle\Manager\SettingsManagerInterface;

class MyController extends AbstractController {

    public function resetSettings(SettingsManagerInterface $settingsManager) {
        $appearanceSettings = $settingsManager->get(AppearanceSettings::class);

        // Reset the settings to their default values
        $settingsManager->resetToDefaultValues($appearanceSettings);
    }
}

Profiler

If you are using Symfony profiler, you should be able to see a new "Settings" panel in the profiler. It shows all settings classes with their parameters defined in your application and their resolved metadata (like which storage adapter to use, which parameter types should be used for mapping, etc.). You can also see the current values of the settings objects and their parameters to the time of the request, which is useful for debugging.

And many more

The bundle has many more features, like automatic form generation for easy changeable settings in the WebUI, easy versioning of settings with migrations, and much more.

These features will be explained more in the next parts of this tutorial. If you wanna check them out now, you can take a look at the documentation of the bundle, where every feature and option of the bundle is explained in detail.