README

Setting bundle is a bundle of the Symfony framework that allows you to easily define, read and change settings.

Integrated with:

symfony cache
doctrine orm
symfony profiler
symfony serializer
twig

Installation & configuration
Usage
Data storages
Data transformers
- Doctrine data transformer
Cache
More effective user (setting owner) passing
Twig
Symfony profiler

Installation & configuration

Run composer require

composer require dwalczyk/setting-bundle

create file config/dwalczyk_setting.yaml and paste the contents from below:

dwalczyk_setting:

  data_storage: 'DWalczyk\SettingBundle\Extension\Doctrine\DataStorage\DoctrineDataStorage'
  #cache: cache.app

  #definitions: []

Add to config/doctrine.yaml

doctrine:
    orm:
        mappings:
            SettingBundle:
                is_bundle: true
                dir: 'Resources/config/doctrine'
                prefix: 'DWalczyk\SettingBundle\Extension\Doctrine\Entity'
                alias: SettingBundle

Create and execute migration

php bin/console doctrine:migrations:diff
php bin/console d:m:m

Usage

First we need to define the setting.

via php

<?php

declare(strict_types=1);

namespace App;

use DWalczyk\SettingBundle\AbstractSettingExtension;
use DWalczyk\SettingBundle\SettingDefinition;

final class SettingExtension extends AbstractSettingExtension
{
    public function getDefinitions(): array
    {
        return [
            new SettingDefinition(name: 'black_mode', type: 'bool', defaultValue: false),
        ];
    }
}

or via yaml configuration

dwalczyk_setting:
  definitions:

    black_mode:
        type: bool
        default_value: false

Now you can read or set value globally or per user.

#[Route('/')]
public function test(SettingsInterface $settings): Response
{
    $settings->get('black_mode'); // false
    $settings->get('black_mode', 'John'); // false

    // set "global scope" value
    $settings->set('black_mode', true);

    $settings->get('black_mode'); // true
    $settings->get('black_mode', 'John'); // true

    // set "user scope" value
    $settings->set('black_mode', false, 'John');

    $settings->get('black_mode'); // true
    $settings->get('black_mode', 'John'); // false

    // ...
}

Data storages

Data storages are classes responsible for writing and reading previously saved settings.

Available built-in data storages:

DWalczyk\SettingBundle\Extension\Doctrine\DataStorage\DoctrineDataStorage - Doctrine ORM storage

You can create your custom data storage, just create symfony service that implements DWalczyk\SettingBundle\DataStorageInterface and insert its name to configuration.

namespace App\DataStorage;

use DWalczyk\SettingBundle\DataStorageInterface;

class Custom implements DataStorageInterface
{
    public function read(string $name, ?string $ownerIdentifier): ?string
    {
        // TODO: Implement read() method.
    }

    public function write(string $name, ?string $value, ?string $ownerIdentifier): void
    {
        // TODO: Implement write() method.
    }
}

dwalczyk_setting:

  data_storage: 'App\DataStorage\Custom'

Data transformers

Data transformers determine how to format data before writing and after reading from data storage.

They are also responsible for formatting the values from the "defaultValue" definition.

Built-in data transformers:

DoctrineDataTransformer - handle doctrine types, read more
SerializerDataTransformer - handle all types supported by symfony serializer
NativePhpSerializerDataTransformer - handle all types supported by serialize/unserialize native php functions

By default, data transformers are loaded in the order:

DoctrineDataTransformer
SerializerDataTransformer

If you want to use NativePhpSerializerDataTransformer instead of SerializerDataTransformer add this code to your config:

services:
  DWalczyk\SettingBundle\Extension\Core\DataTransformer\NativePhpSerializerDataTransformer:
    tags:
      - { name: 'dwalczyk_setting.data_transformer', priority: 1 }

Or create custom data transformer

<?php

namespace App;

use DWalczyk\SettingBundle\DataTransformerInterface;
use Symfony\Component\DependencyInjection\Attribute\AsTaggedItem;

#[AsTaggedItem('dwalczyk_setting.data_transformer', priority: 2)]
class CustomDataTransformer implements DataTransformerInterface
{
    // implement required methods
}

DoctrineDataTransformer

Supported types:

doctrine-entity<fqcn/of/entity> - single entity e.g. doctrine-entity<App\Mail\Entity\MailTemplate>
doctrine-entity<fqcn/of/entity>[] - multiple entity e.g. doctrine-entity<App\Mail\Entity\MailTemplate>[]

Cache

To use cache, you must configure cache in your symfony configuration and then cache option in the bundle configuration.

framework:
    cache:
        app: cache.adapter.filesystem

dwalczyk_setting:
  cache: cache.app

or with custom pool:

framework:
    cache:
        pools:
            setting_pool:
                adapter: cache.adapter.filesystem

dwalczyk_setting:
  cache: setting_pool

if you don't want to use cache, leave the cache option empty or do not define it.

More effective user (setting owner) passing

Implement SettingOwnerInterface in your security user class.

class User implements UserInterface, PasswordAuthenticatedUserInterface, SettingOwnerInterface
{
    public function getSettingIdentifier(): string
    {
        return (string) $this->id;
    }

    ...
}

Now you are able to call:

#[Route('/')]
public function test(SettingsInterface $settings): Response
{
    $settings->get('black_mode', $this->getUser());
    // or
    $settings->set('black_mode', true, $this->getUser());
    
    // ...
}

Twig

Functions:

{{ setting(settingName) }}

dwalczyk / setting-bundle

Maintainers

Details