README

• Define your settings as php classes.
• Settings are stored in database in a single table.
• Bundle provides GUI to edit settings, customisable in setting definition classes.
• Define your scopes: each scope has its own settings, setting inheritance is supported.
• You can define multiple collections with different settings/scopes/config.

You can take a look in the Tests/TestApp for working examples.

Check out the online example application. (It's source is also available.)

Get Started

You have to do at least the following things to be able to use this settings editor:

1. Install - This is the usual Symfony bundle installation with some additional suggested packages which you might already have installed.
2. Database Setup - You will need a table where the settings are stored.
3. Defining Settings - Define your editable settings as PHP classes, and tell this bundle about them in its configuration file.
4. Setting up the editor - Add the editor controller to your router.

Furthermore, there are links to more advanced use cases in the sections below and at the end of this readme.

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 tzunghaor/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 tzunghaor/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 [
    // ...
    Tzunghaor\SettingsBundle\TzunghaorSettingsBundle::class => ['all' => true],
];

Additional recommended packages

• phpdocumentor/reflection-docblock - With this installed, you have more possibilities to define your settings in docblocks. (Without this you still can configure everything using PHP attributes.)
• symfony/asset - Whe setting editor twig template uses asset() - if you don't have symfony/asset installed, then you have to override editor_page.html.twig: see twig customization
• symfony/serializer - If serializer is installed and enabled then your setting class properties can be any serializable class or array of objects of a class. (Without this you have to write your own setting converter code if you want to use classes as setting properties.)
• symfony/validator - With this you can define validation rules on your setting classes that will be used in the setting editor. See symfony validation.
• symfony/security-bundle or only symfony/security-core - With this you can create security voters to manage who can edit which settings. See security voters

Setup

Database Setup

You need a database table to store your settings - the easiest way is to use the entity definition provided by this bundle. If you have auto mapping enabled in doctrine, then you can skip to Create Table.

#config/packages/doctrine.yaml
doctrine:
  orm:
    auto_mapping: false
    mappings:
      Tzunghaor\SettingsBundle:
        type: attribute
        dir: '%kernel.project_dir%/vendor/tzunghaor/settings-bundle/src/Entity'
        prefix: 'Tzunghaor\SettingsBundle\Entity'

Create Table

To actually create the table, use preferably doctrine migrations:

$ bin/console doctrine:migrations:diff
$ bin/console doctrine:migrations:migrate

or the fast and dangerous way on your developer machine:

$ bin/console doctrine:schema:update --force

More about the database table

Defining Setting Section Classes

You can define your settings in php classes (I will call these classes "setting sections", or simply "sections"), for example create a directory for your settings (e.g. src/Settings), and create a BoxSettings.php in it:

// src/Settings/BoxSettings.php
namespace App\Settings;
use Tzunghaor\SettingsBundle\Attribute\Setting;

class BoxSettings
{
    public int $padding = 0;

    /**
     * @var string[]
     */
    #[Setting(enum: ["bottom", "top", "left", "right"])]
    public $borders = [];
}

Since at the beginning no settings are stored in the database, it is best to set sensible default values for every class property as seen above.

More about setting classes

Then tell specify in the bundle config where your setting classes are:

# config/packages/tzunghaor_settings.yaml
tzunghaor_settings:
  collections:
    # Each entry under "tzunghaor_settings" configures a setting collection.
    # Use "default" if you define only one collection
    default:
      mapping:
        # The root directory of your settings. 
        # All php files in it and its subdirectories will be 
        #  handled as setting sections.
        dir: '%kernel.project_dir%/src/Settings'
        # The php namespace in the directory. 
        prefix: App\Settings\

Now you can get your settings from the service provided by the bundle.

use App\Settings\BoxSettings;
use Tzunghaor\SettingsBundle\Service\SettingsService;

class MyService
{
    // ...
    
    public function __construct(SettingsService $settingsService)
    {
        /** 
         * declaring variable type for auto-complete support in IDE
         * @var BoxSettings $boxSettings 
         */
        $boxSettings = $settingsService->getSection(BoxSettings::class);
        $doublePadding = $boxSettings->padding * 2; 

More on collections and services

Setting up the editor

If you have symfony/asset installed then you can skip to setting up the route. Otherwise, you first have to overwrite a twig template: create a new directory in your application templates/bundles/TzunghaorSettingsBundle, copy Resources/views/editor_page.html.twig there, remove the "ts_stylesheets" and "ts_javascripts" blocks, and load the .js and .css of the bundle without asset().

Add the route defined by the bundle to your routes:

# config/routes.yaml

tzunghaor_settings_editor:
  resource: '@TzunghaorSettingsBundle/config/routes.php'
  prefix: '/settings'

Then go to https://your.domain/settings/edit/ in your browser.

You probably want to set up some firewall rules in your security config for this controller, and/or use security voters.

You can have more control on the editor with route definition, see routing.

Advanced Usage

Setting up cache

It is advised to use a cache with this bundle - if you don't configure one, then the bundle will create its own in-memory cache which is cleared on each request (this is good for development, but not that performant on production).

E.g. to use the default Symfony application cache:

# config/packages/tzunghaor_settings.yaml

tzunghaor_settings:
  collections:
    default:
      cache: 'cache.app'

Keep in mind that you need to clear the cache every time you make changes in your setting section PHP files.

Collections with nested scopes need a cache implementing TagAwareCacheInterface. You can easily set up one in your Symfony framework config:

# config/packages/frameword.yaml

framework:
  cache:
    pools:
      cache.tagged:
        adapter: cache.adapter.filesystem
        tags: true

Using scopes

If you need different values for the same setting in different scenarios, then you can use scopes:

# config/packages/tzunghaor_settings.yaml

tzunghaor_settings:
  collections:
    default:
      # tag aware cache needed when using nested scopes
      cache: 'cache.app.taggable'
      default_scope: day
      scopes:
        - name: day
          children:
            - name: morning
            - name: afternoon
        - name: night

Use only alphanumeric characters and underscores as scope names.

You can build arbitrary deep hierarchies (child nodes can have children, etc.), but if you use nested scopes (meaning you have at least one "children" node) you will need a tag aware cache, see Symfony\Contracts\Cache\TagAwareCacheInterface.

The SettingsService::getSection() will use default_scope when called without subject. Otherwise, you need to pass it the scope name as subject.

It can be useful to have your webserver set an environment variable based on the request, and use that in your config:

# config/packages/tzunghaor_settings.yaml

tzunghaor_settings:
  collections:
    default:
      default_scope: %env(DEFAULT_SCOPE)%
      ...

For more advanced use (e.g. having one scope per user), you can define your own scope provider