README

CreativePointSettingsBundle manages configurations settings in the database and make them available via DTO objects in your Symfony application.

Installation

Make sure Composer is installed globally, as explained in the installation chapter of the Composer documentation.

Applications that use Symfony Flex

Open a command console, enter your project directory and execute:

$ composer require cpoint-eu/settings-bundle

Applications that don't use Symfony Flex

Step 1: Download the Bundle

Open a command console, enter your project directory and execute the following command to download the latest stable version of this bundle:

$ composer require cpoint-eu/settings-bundle

Step 2: Enable the Bundle

Then, enable the bundle by adding it to the list of registered bundles in the config/bundles.php file of your project:

// config/bundles.php

return [
    // ...
    CreativePoint\SettingsBundle\CreativePointSettingsBundle::class => ['all' => true],
];

Configuration

The bundle configuration is optional and in most cases does not need to be changed in any way.

creative_point_settings:
  # [settings_%s] Settings cache key. %s is replaced by the setting name
  cache_key: 'your_cache_key_%s'

  # [604800] cache TTL
  cache_ttl: 400
  
  objects:
    # [cp_settings] table name in the database  
    table_name: 'your_table_name'

    # [CreativePoint\SettingsBundle\Entity\Settings] your settings entity
    model: 'APP\Entity\Settings'

    # [null] your custom settings entity repository
    repository: 'APP\Repository\Settings'

Usage

You must create a DTO object that implements CreativePoint\SettingsBundle\Model\SettingsDtoInterface.

//...
use CreativePoint\SettingsBundle\Model\SettingsDtoInterface;

class MySettingsDto implements SettingsDtoInterface
{
    private const SETTINGS_ID = 'mySettings';

    public function __construct(
        public ?string $someValue = 'default value',
        public ?int $someNumber = 254,
    ) {
    }

    public static function getSettingsId(): string
    {
        return self::SETTINGS_ID;
    }
}

Save settings data

// ...
use CreativePoint\SettingsBundle\Factory\SettingFactoryInterface;

// ...

// Save settings to the database
public function saveSettings(SettingFactoryInterface $factory)
{
    // Set data from array
    $factory->setSettingsData('mySettings', [
        'someValue' => 'new value',
        'someNumber' => 123,
    ]);
    
    // Set data from DTO
    $dto = new MySettingsDto(
        'new value',
        123,
    );
    
    $factory->setSettingsDataFromDto($dto);
}

Load settings data

// ...
use CreativePoint\SettingsBundle\Provider\SettingsProvider;

// ...

// Save settings to the database
public function loadSettings(SettingsProviderInterface $provider)
{
    // Load data from DB by DTO::SETTINGS_ID and return DTO
    $settings = $provider->loadSettingsDto('mySettings');
    // ...or load SettingsEntity itself
    $settings = $provider->getSettingsEntity('mySettings');
    
    // You can also load your DTO from array data
    $settings = $provider->loadSettingsDtoFromArray('mySettings', [
        'someValue' => 'new value',
        'someNumber' => 123,
    ]);
}

Override settings entity

The settings entity can be overridden if necessary. The newly created entity must extend the base Settings entity CreativePoint\SettingsBundle\Entity\Settings or implement CreativePoint\SettingsBundle\Entity\SettingsInterface. Then you need to modify the bundle configuration:

creative_point_settings:
  objects:
    model: 'APP\Entity\YourSettingsEntity'

You can replace SettingsRepository in the same way. Your new repository must extend CreativePoint\SettingsBundle\Repository\SettingsRepository or implement CreativePoint\SettingsBundle\Repository\SettingsRepositoryInterface. And make the bundle aware of it:

creative_point_settings:
  objects:
    repository: 'APP\Repository\YourSettingsRepository'