Provides a nice way to define variables and inject them into application parts.
- Supporting
bool
,string
,int
,float
,array
as setting values. - Multiple providers.
- User interface.
-
composer require helis/settings-manager-bundle
-
Register bundle to
AppKernel.php
(Symfony3) orconfig/bundles.php
(Symfony4)
<?php
class AppKernel extends Kernel
{
public function registerBundles()
{
return [
new Helis\SettingsManagerBundle\HelisSettingsManagerBundle(),
];
}
}
- Add an example configuration to
app/config/config.yml
(Symfony3) orconfig/packages/settings_manager.yaml
(Symfony4)
helis_settings_manager:
settings:
- name: foo
description: 'foo desc'
type: bool
data: false
tags:
- 'super_switch'
- name: baz
description: 'master toggle for awesome new feature'
type: string
data: fish
tags:
- 'experimental'
- 'poo'
- Now, the easiest way to get settings in your services is by using
SettingsRouterAwareTrait
. The service will be automatically injected by autowire. Then just ask for setting:
use Helis\SettingsManagerBundle\Settings\Traits\SettingsRouterAwareTrait;
class MuchAmazingService
{
use SettingsRouterAwareTrait;
public function doSmth()
{
if ($this->settingsRouter->getBool('foo')) {
// do it
}
// just do it
}
}
To get settings into your services, you have a few choices:
SettingsRouter is pretty straight-forward. It has one main method, called $settingsRouter->get($settingName, $default = null)
, which returns a setting of any type. If the setting is missing, default value will be returned. Other getters are aliases for get
but with declared return types and appropriate default values.
Method name | Default value | Declared return type |
---|---|---|
getString |
'' |
string |
getBool |
false |
bool |
getInt |
0 |
int |
getFloat |
0.0 |
float |
getArray |
[] |
array |
If you dont want to inject SettingsRouter
or wish for a cleaner service, service tags are here to help. First of all, the service must have a setter, which can be used to inject a setting value. For bool values, the bundle provides the SwitchableTrait
, which adds setEnabled
and isEnabled
methods. Then add a tag on your service with attributes setting
for setting name and method
for method name. Example:
AppBundle\Service\AmazingService:
tags:
- { name: settings_manager.setting_aware, setting: foo, method: setEnabled }
Base setting model.
Property | Type | Description |
---|---|---|
$name | string | Setting name |
$description | string | Setting descrption |
$domain | DomainModel | Domain model |
$tags | Collection[Tag] | Collection of tags |
$type | Enum[Type] | Determines setting value type |
$data | array | Holds actual value for setting |
$providerName | string | Internal field to know from which provider this setting is |
Domain is like a group for settings. Setting cannot exist without domain. The default is named default
, which is also always enabled. Domain can hold only one setting with the same name. Settings with the same names must be in different domains. When a setting is requested, the one from a higher priority domain will be returned.
Property | Type | Description |
---|---|---|
$name | string | Domain name |
$priority | int (default: 0) | Domain priority |
$enabled | bool (default: false) | Is domain enabled indication |
$readOnly | bool (default: false) | is domain only readable indication |
Enum which holds supported types for setting. Values:
- STRING
- BOOL
- INT
- FLOAT
- YAML
- CHOICE
Settings can be pulled from multiple sources. Currently, the bundle comes with 4 settings providers. They can be configured and prioritized. If a setting with the same name will come from >1 providers, setting from provider with higher priority will override settings from lower priority providers.
Settings can be easily mutated in providers using user interface.
Settings providers:
And additional 2 decorating providers:
Helis\SettingsManagerBundle\Provider\SimpleSettingsProvider
This is a provider, which only holds settings collections. Currently, it's being used to hold settings from configuration, but many more can be configured.
To configure additional simple providers, factory is provided because provider can only accept already denormalized objects.
Configuration example:
setting_provider_factory.foo:
class: Helis\SettingsManagerBundle\Provider\Factory\SimpleSettingsProviderFactory
arguments:
$serializer: '@settings_manager.serializer'
$normalizedData:
-
- name: foo
description: 'foo desc'
type: bool
domain: { name: default }
data: { value: false }
tags: [{ name: 'super_switch' }]
tags:
- { name: settings_manager.provider_factory, provider: foo, priority: 10 }
Helis\SettingsManagerBundle\Provider\DoctrineOrmSettingsProvider
This is a provider which reads and saves settings using EntityManagerInterface
.
Required libraries:
I am guessing you already have it ๐ฎ
composer require doctrine/orm acelaya/doctrine-enum-type
Configuration example:
- Doctrine configuration
# Symfony3, app/config/config.yml
# Symfony4, config/packages/doctrine.yaml
doctrine:
orm:
mappings:
HelisSettingsManagerBundle:
type: yml
is_bundle: true
dir: "Resources/config/doctrine"
alias: HelisSettingsManagerBundle
prefix: Helis\SettingsManagerBundle
- Create setting entity
<?php
declare(strict_types=1);
namespace App\Entity;
use Doctrine\ORM\Mapping as ORM;
use Helis\SettingsManagerBundle\Model\SettingModel;
/**
* @ORM\Entity()
* @ORM\Table(name="setting")
*/
class Setting extends SettingModel
{
/**
* @var int
*
* @ORM\Id
* @ORM\GeneratedValue
* @ORM\Column(type="integer")
*/
protected $id;
}
-
Update your doctrine schema.
-
Register settings provider:
Helis\SettingsManagerBundle\Provider\DoctrineOrmSettingsProvider:
arguments:
$entityManager: '@doctrine.orm.default_entity_manager'
$settingsEntityClass: 'App\Entity\Setting'
tags:
- { name: settings_manager.provider, provider: orm, priority: 20 }
Helis\SettingsManagerBundle\Provider\CookieSettingsProvider
This is a provider, which only enables existing settings by using a cookie. Cookies are encoded, so that they could not be randomly enabled by users.
Required libraries:
composer require paragonie/paseto
Paseto
is used to encrypt cookies.
Configuration example:
Helis\SettingsManagerBundle\Provider\CookieSettingsProvider:
arguments:
$serializer: '@settings_manager.serializer'
tags:
- { name: settings_manager.provider, provider: cookie, priority: 30 }
- { name: kernel.event_subscriber }
Helis\SettingsManagerBundle\Provider\AsymmetricCookieSettingsProvider
This is a provider, which only enables existing settings by using a cookie. Cookies are encoded with asymmetric private and public keys, so that they could not be randomly enabled by users.
Required libraries:
composer require paragonie/paseto
Paseto
is used to encrypt cookies.
Configuration example:
Helis\SettingsManagerBundle\Provider\AsymmetricCookieSettingsProvider:
arguments:
$serializer: '@settings_manager.serializer'
tags:
- { name: settings_manager.provider, provider: asymmetric_cookie, priority: 40 }
- { name: kernel.event_subscriber }
Helis\SettingsManagerBundle\Provider\AwsSsmSettingsProvider
This is a provider, which is used only for reading and updating existing ssm parameters as settings.
Required libraries:
composer require aws/aws-sdk-php
Configuration example:
Helis\SettingsManagerBundle\Provider\AwsSsmSettingsProvider:
arguments:
- '@Aws\Ssm\SsmClient'
- '@settings_manager.serializer'
- ['amazing_parameter_name']
tags:
- { name: settings_manager.provider, provider: aws_ssm }
Helis\SettingsManagerBundle\Provider\DecoratingRedisSettingsProvider
This provider is used to cache other settings providers like DoctrineORM or AWS SSM. It uses Redis client, not doctrine/cache providers or symfony/cache adapters because we want to take advantage of redis data structures for simplier invalidation process.
Required extensions:
pecl install redis-3.1.6
Configuration example:
Helis\SettingsManagerBundle\Provider\DecoratingRedisSettingsProvider:
decorates: 'Helis\SettingsManagerBundle\Provider\DoctrineOrmSettingsProvider'
arguments:
$decoratingProvider: 'Helis\SettingsManagerBundle\Provider\DecoratingRedisSettingsProvider.inner'
$redis: '@settings.cache.redis' # you need to register your own \Redis client in container
$serializer: '@settings_manager.serializer'
Helis\SettingsManagerBundle\Provider\DecoratingPredisSettingsProvider
Same as phpredis decorating settings provider It just replaces the phpredis extension with predis.
Required libraries:
composer require predis/predis
helis_settings_manager:
settings:
-
name: foo
description: 'foo desc'
domain: default # Used for grouping settings.
type: bool
data: false
tags: [super_switch]
profiler:
enabled: false
logger:
enabled: false
service_id: null # Psr\Log\LoggerInterface service id
settings_files:
# - '%kernel.root_dir%/config/extra_settings.yml'
User interface can be used to change setting values, enable or disable domains.
-
Bundled user interface requires knp-menu-bundle, jsrouting-bundle.
composer require symfony/translation symfony/twig-bundle symfony/asset knplabs/knp-menu-bundle friendsofsymfony/jsrouting-bundle
-
Include routing file.
# Symfony3, app/config/routing.yml
# Symfony4, config/routes/settings_manager.yaml
settings_manager:
resource: '@HelisSettingsManagerBundle/Resources/config/routing.yml'
prefix: /settings
That's it. Now go to the /settings
path and you will see the settings user interface.
The Twig extension is also added to get settings in your twig templates. Just like in SettingsRouter
, first argument is the setting name and the second sets default value.
{{ setting_get('foo', false) }}
Helis\SettingsManagerBundle\Controller\Traits\SettingsControllerTrait
Adds a method to deny access, unless a setting is enabled. It's using SettingsRouter
, which, again, will be injected by autowire.
public function indexAction(): Response
{
$this->denyUnlessEnabled('index_page');
...
}
New feature branches should be created from the master branch.