PHPackages                             tzunghaor/settings-bundle - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. tzunghaor/settings-bundle

ActiveSymfony-bundle

tzunghaor/settings-bundle
=========================

Database persisted settings

0.16.1(9mo ago)97.3k↓16.7%1[1 issues](https://github.com/tzunghaor/settings-bundle/issues)MITPHPPHP >=8.0CI passing

Since Jan 24Pushed 9mo ago2 watchersCompare

[ Source](https://github.com/tzunghaor/settings-bundle)[ Packagist](https://packagist.org/packages/tzunghaor/settings-bundle)[ RSS](/packages/tzunghaor-settings-bundle/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (20)Versions (17)Used By (0)

Tzunghaor Settings Bundle
=========================

[](#tzunghaor-settings-bundle)

[![test badge](https://github.com/tzunghaor/settings-bundle/actions/workflows/test.yml/badge.svg?event=push)](https://github.com/tzunghaor/settings-bundle/actions/workflows/test.yml/badge.svg?event=push)

[![editor](docs/editor.png)](docs/editor.png)

- 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](https://primandras.hu/settings-example/). (It's [source](https://github.com/tzunghaor/settings-bundle) is also available.)

Get Started
===========

[](#get-started)

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

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

Furthermore, there are links to more advanced use cases in the above listed sections and [at the end of this readme](#advanced-usage).

Installation
============

[](#installation)

Make sure Composer is installed globally, as explained in the [installation chapter](https://getcomposer.org/doc/00-intro.md)of the Composer documentation.

Applications that use Symfony Flex
----------------------------------

[](#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
----------------------------------------

[](#applications-that-dont-use-symfony-flex)

### Step 1: Download the Bundle

[](#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

[](#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
-------------------------------

[](#additional-recommended-packages)

- **phpdocumentor/reflection-docblock** - with this installed, you have more possibilities to define your settings
- **symfony/asset** - the setting editor twig template uses asset() - if you don't have it installed, then you have to override **editor\_page.html.twig**: see [twig customization](docs/twig.md)
- **symfony/validator** - with this you can define validation rules on your setting classes that will be used in the setting editor. See [symfony validation](https://symfony.com/doc/current/validation.html).
- **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](docs/voter.md)

Setup
=====

[](#setup)

Database 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 this configuration step.

```
#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
------------

[](#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](docs/database.md)

Defining Setting Classes
------------------------

[](#defining-setting-classes)

You can define your settings in php classes (I will call such classes as 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
{
    /**
     * @var int
     */
    public $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 in your class.

[More about setting classes](docs/define_section.md)

Then tell the bundle where your settings classes are in the config:

```
# 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](docs/collections.md)

Setting up the editor
---------------------

[](#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** to there, remove the "ts\_stylesheets" and "ts\_javascripts" blocks, and use your method to load the .js and .css of the bundle.

Add the route defined by the bundle to your routes:

```
# config/routes.yaml

tzunghaor_settings_editor:
  resource: '@TzunghaorSettingsBundle/config/routes.xml'
  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](docs/voter.md).

You can have more control on the editor with route definition, see [routing](docs/routing.md).

Advanced Usage
==============

[](#advanced-usage)

Setting up cache
----------------

[](#setting-up-cache)

It is advised to use a cache with this bundle, e.g. use the default Symfony application cache:

```
# config/packages/tzunghaor_settings.yaml

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

If you don't specify one, then the application's default cache will be used.

Currently, 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.

Using scopes
------------

[](#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](docs/scopes.md)

###  Health Score

41

—

FairBetter than 89% of packages

Maintenance55

Moderate activity, may be stable

Popularity29

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~127 days

Recently: every ~141 days

Total

14

Last Release

283d ago

PHP version history (3 changes)0.1.0PHP >=7.1

0.13PHP >=7.4

0.14PHP >=8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/66c51e5406b1cb327e81ff2eefd8be4832bdf6c29e5fff13d606076266af596d?d=identicon)[tzunghaor](/maintainers/tzunghaor)

---

Top Contributors

[![tzunghaor](https://avatars.githubusercontent.com/u/35069828?v=4)](https://github.com/tzunghaor "tzunghaor (23 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Rector

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tzunghaor-settings-bundle/health.svg)

```
[![Health](https://phpackages.com/badges/tzunghaor-settings-bundle/health.svg)](https://phpackages.com/packages/tzunghaor-settings-bundle)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M651](/packages/sylius-sylius)[prestashop/prestashop

PrestaShop is an Open Source e-commerce platform, committed to providing the best shopping cart experience for both merchants and customers.

9.0k15.4k](/packages/prestashop-prestashop)[easycorp/easyadmin-bundle

Admin generator for Symfony applications

4.3k16.7M310](/packages/easycorp-easyadmin-bundle)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.3M152](/packages/sulu-sulu)[ec-cube/ec-cube

EC-CUBE EC open platform.

78527.0k1](/packages/ec-cube-ec-cube)[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)