craue / config-bundle
Database-stored settings made available via a service for your Symfony project.
Installs: 882 608
Dependents: 4
Suggesters: 0
Security: 0
Stars: 173
Watchers: 14
Forks: 35
Open Issues: 14
Type:symfony-bundle
Requires
- php: ^7.3|^8
- doctrine/doctrine-bundle: ^1.6.12|^2
- psr/simple-cache: ^1|^2|^3
- symfony/cache: ~4.4|~5.4|^6.3
- symfony/config: ~4.4|~5.4|^6.3
- symfony/dependency-injection: ~4.4|~5.4|^6.3
- symfony/form: ~4.4|~5.4|^6.3
- symfony/framework-bundle: ~4.4|~5.4|^6.3
- symfony/http-foundation: ~4.4|~5.4|^6.3
- symfony/http-kernel: ~4.4|~5.4|^6.3
- symfony/options-resolver: ~4.4|~5.4|^6.3
- symfony/validator: ~4.4|~5.4|^6.3
Requires (Dev)
- craue/translations-tests: ^1.0
- doctrine/orm: ^2.5.14
- phpstan/extension-installer: ^1.1
- phpstan/phpstan: ^1.4
- phpstan/phpstan-deprecation-rules: ^1.0
- phpstan/phpstan-strict-rules: ^1.1
- phpstan/phpstan-symfony: ^1.1
- phpunit/phpunit: ^9.6
- symfony/asset: ~4.4|~5.4|^6.3
- symfony/browser-kit: ~4.4|~5.4|^6.3
- symfony/phpunit-bridge: ^6.3
- symfony/twig-bundle: ~4.4|~5.4|^6.3
- symfony/web-profiler-bundle: ~4.4|~5.4|^6.3
README
CraueConfigBundle manages configuration settings stored in the database and makes them accessible via a service in your
Symfony project. These settings are similar to those defined in parameters.yml
but can be modified at runtime, e.g.
by an admin user.
Installation
Get the bundle
Let Composer download and install the bundle by running
composer require craue/config-bundle
in a shell.
Enable the bundle
If you don't use Symfony Flex, register the bundle manually:
// in config/bundles.php return [ // ... Craue\ConfigBundle\CraueConfigBundle::class => ['all' => true], ];
Create the table
Preferably you do this by calling
# in a shell
php bin/console doctrine:migrations:diff
php bin/console doctrine:migrations:migrate
or
# in a shell
php bin/console doctrine:schema:update
or however you like.
Add the route to manage settings (optional)
You can either import the default routing configuration
# in app/config/routing.yml craue_config_settings: resource: "@CraueConfigBundle/Resources/config/routing/settings.xml" prefix: /settings
...or add your own to have full control over the URL pattern.
# in app/config/routing.yml craue_config_settings_modify: path: /settings/modify defaults: _controller: Craue\ConfigBundle\Controller\SettingsController::modifyAction
Some CSS is needed to render the form correctly. Install the assets in your project:
# in a shell
php bin/console assets:install --symlink web
Usage
Defining settings
This bundle does not provide functionality to create new settings because this would make no sense at runtime.
Those settings will be used in your application and thus code needs to be written for that.
This means that you have to create new settings in the database table craue_config_setting
yourself, e.g. using a
migration.
Managing settings' values
If you added the route described above you can manage the values of all defined settings in a simple form.
By default, you can access that form by browsing to /settings/modify
.
But you probably want to limit access to this form in your security configuration.
Reading and writing settings
For accessing settings, the bundle provides the service Craue\ConfigBundle\Util\Config
.
To use it directly in a controller, either add an autowired type-hinted argument to the action...
// in src/Controller/MyController.php use Craue\ConfigBundle\Util\Config; public function indexAction(Config $config) { // use $config }
...or let your controller extend Symfony\Bundle\FrameworkBundle\Controller\AbstractController
and make the
service alias craue_config
available by defining getSubscribedServices
:
// in src/Controller/MyController.php use Craue\ConfigBundle\Util\Config; public function indexAction() { // use $this->get('craue_config') } public static function getSubscribedServices() { return array_merge(parent::getSubscribedServices(), [ 'craue_config' => Config::class, ]); }
The service defines the following methods:
all()
- get an associative array of all defined settings and their valuesget($name)
- get the value of the specified settinggetBySection($section)
- likeall()
, but get only settings within the specified section (or those without a section if explicitly passingnull
)set($name, $value)
- set the value of the specified settingsetMultiple([$name1 => $value1, $name2 => $value2])
- set values for multiple settings at once
Keep in mind that each setting has to be present, or an exception will be thrown.
Usage in Twig templates
The Twig extension in this bundle supports reading settings directly in your template.
{{ craue_setting('name-of-a-setting') }}
Enable caching (optional)
To reduce the number of database queries, you can set up a cache for settings. First, you have to choose which cache implementation you'd like to use. Currently, there are adapters available for:
Refer to the documentation of each implementation for details and read on in the corresponding section below. When
done, CraueConfigBundle
will automatically cache settings (using the built-in craue_config_cache_adapter
service).
Keep in mind to clear the cache (if needed) after modifying settings outside of your app (e.g. by Doctrine migrations):
# in a shell
php bin/console doctrine:cache:clear craue_config_cache
Cache implementation: DoctrineCacheBundle
Set the parameter craue_config.cache_adapter.class
appropriately and configure a so-called cache provider with the
alias craue_config_cache_provider
:
# in app/config/config.yml parameters: craue_config.cache_adapter.class: Craue\ConfigBundle\CacheAdapter\DoctrineCacheBundleAdapter doctrine_cache: providers: craue_config_cache: apc: ~ namespace: craue_config aliases: - craue_config_cache_provider
Cache implementation: Symfony Cache component
Set the parameter craue_config.cache_adapter.class
appropriately and configure a so-called cache pool with the
service id craue_config_cache_provider
:
# in app/config/config.yml parameters: craue_config.cache_adapter.class: Craue\ConfigBundle\CacheAdapter\SymfonyCacheComponentAdapter services: craue_config_cache_provider: class: Symfony\Component\Cache\Adapter\FilesystemAdapter public: false arguments: - 'craue_config' - 0 - '%kernel.cache_dir%'
Customization
Redirect to a different page after submitting the built-in form
If you've enabled the build-in form, you can define where to redirect on successfully saving the changes by setting the target route name:
# in app/config/parameters.yml parameters: craue_config.redirectRouteAfterModify: craue_config_settings_modify
Rendering of settings in sections
If you want to render settings in a group (called section here), you'll have to assign those settings a common section name (in the database). Optionally, you can influence the order of these sections:
# in app/config/parameters.yml parameters: craue_config.configTemplate.sectionOrder: [section1, section2, section3]
Settings without a section will be rendered at first. Sections without explicit ordering are rendered at last.
Translation
You can add translations for all settings (and sections) to be shown in the form by adding them to translation files
with the CraueConfigBundle
domain, e.g.
# in app/Resources/CraueConfigBundle/translations/CraueConfigBundle.en.yml name-of-a-setting: name of the setting # in app/Resources/CraueConfigBundle/translations/CraueConfigBundle.de.yml name-of-a-setting: Name der Einstellung
Using a custom entity for settings
The custom entity has to provide a mapping for the field value
. The class BaseSetting
defines this field, but no
mapping for it. This allows easy overriding, including the data type. In the following example, the value
field will
be mapped to a text
column, which will in turn render the built-in form fields as textarea
.
So create the entity and its appropriate mapping:
// src/MyCompany/MyBundle/Entity/MySetting.php use Craue\ConfigBundle\Entity\BaseSetting; use Doctrine\ORM\Mapping as ORM; /** * @ORM\Entity(repositoryClass="Craue\ConfigBundle\Repository\SettingRepository") * @ORM\Table(name="my_setting") */ class MySetting extends BaseSetting { /** * @var string|null * @ORM\Column(name="value", type="text", nullable=true) */ protected $value; /** * @var string|null * @ORM\Column(name="comment", type="string", nullable=true) */ protected $comment; public function setComment($comment) { $this->comment = $comment; } public function getComment() { return $this->comment; } }
And make the bundle aware of it:
# in app/config/config.yml craue_config: entity_name: MyCompany\MyBundle\Entity\MySetting