LexxpavlovSettingsBundle
This bundle helps you to manage your settings in Symfony2/3/4 project., (*1)
Settings has one of types: Boolean, Integer, Float, String, Text, Html. You may get one concrete setting or fetch group
of settings. Fetching of settings may be cached by your cache provider used in project., (*2)
Management of settings provides by SonataAdminBundle. In other case you may manage settings via code by use special
functions or predefined forms., (*3)
Installation
Composer
Download LexxpavlovSettingsBundle and its dependencies to the vendor directory., (*4)
You can use Composer for the automated process:, (*5)
$ composer require lexxpavlov/settingsbundle
or manually add link to bundle into your composer.json and run $ composer update:, (*6)
{
"require" : {
"lexxpavlov/settingsbundle": "~1.2"
}
}
Composer will install bundle to vendor/lexxpavlov/settingsbundle directory., (*7)
Adding bundle to your application kernel
// app/AppKernel.php
public function registerBundles()
{
$bundles = array(
// ...
new Lexxpavlov\SettingsBundle\LexxpavlovSettingsBundle(),
// ...
);
}
Configuration
Bundle does not need any required parameters and will work without changes in config.yml. But you may config some
parameters, read more below., (*8)
Now you need create the tables in your database:, (*9)
$ php bin/console doctrine:schema:update --dump-sql
or in Symfony2:, (*10)
$ php app/console doctrine:schema:update --dump-sql
This will show SQL queries for creating of tables in the database. You may manually run these queries., (*11)
Note.
You may also execute php bin/console doctrine:schema:update --force command, and Doctrine will create needed
tables for you. But I strongly recommend you to execute --dump-sql first and check SQL, which Doctrine will execute., (*12)
Note.
If you use 1.1.* version of bundle, you need to update database., (*13)
Usage
Use SonataAdminBundle for manage your settings. Otherwise use predefined forms. You feel free to
use the bundle if you configure settings with database tool (phpMyAdmin or other) or by use special functions called in
your code (see below)., (*14)
You may put settings to group or not. Groups may be used for fetching several settings at one query., (*15)
Fetching of settings are supported in twig templates or in controller (or in any script where settings service are injected)., (*16)
For example, you created 3 settings:
* page_title without group
* description and keywords in meta group., (*17)
Use in controller
namespace App\YourBundle\Controller;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Template;
class DefaultController extends Controller
{
/**
* @Route("/")
* @Template()
*/
public function indexAction()
{
$settings = $this->get('settings');
$title = $settings->get('page_title');
$meta = $settings->group('meta');
return array(
'title' => $title,
'meta_description' => $meta['description'],
'meta_keywords' => $meta['keywords'],
);
}
}
Use in template
{% extends '::base.html.twig'%}
{% block meta %}
<title>{{ settings('page_title') }}</title>
<meta name="description" content="{{ settings('meta', 'description') }}">
<meta name="keywords" content="{{ settings('meta', 'keywords') }}">
{% endblock %}
Advanced usage
Full configuration
Here is the default configuration for the bundle (all parameters are optional):, (*18)
lexxpavlov_settings:
enable_short_service: true # default true, use false for disable registering 'settings' service
html_widget: ckeditor # default null, valid values are 'null', 'ckeditor'
cache_provider: cache.app # default null, for enable database caching set up name of caching service
use_category_comment: false # default false, use category comment as its title in settings list (in SettingsAdmin)
ckeditor: # set parameters of ckeditor. Not need if IvoryCKEditorBundle is installed
base_path: /ckeditor/
js_path: /ckeditor/ckeditor.js
ckeditor form type may be added by IvoryCKEditorBundle. If you are
using CKEditor without IvoryCKEditorBundle, you must specify the parameters base_path and js_path., (*19)
Groups of settings
For fetch several of settings from one group you may use one of two cases:, (*20)
$param1 = $settings->get('category', 'param1');
$param2 = $settings->get('category', 'param2');
// or
$cat = $settings->group('category');
$param1 = $cat['param1'];
$param2 = $cat['param2'];
Both of cases has an identical perfomance - the whole group will fetch while first access to it, fetching of data will
be only one time., (*21)
Using default value in twig
{% extends '::base.html.twig'%}
{% block meta %}
<title>{{ settings('page_title', null, 'My default title') }}</title>
<meta name="description" content="{{ settings('meta', 'description', 'My default description') }}">
<meta name="keywords" content="{{ settings('meta', 'keywords', 'keywords1, keywords2') }}">
{% endblock %}
Using groups in twig
{% set params = settings_group('category') %}
- {{ params.param1 }}
- {{ params['param-2'] }}
Example of using the settings group
There is an example of group using - settings which used in backend and frontend. Several settings are placed in
client group, and include to template:, (*22)
{# app/Resources/views/base.html.twig #}
{# ... #}
</body></html>
Perfomance and caching
Use caching for increase of fetching settings. If you don't use caching already - it is perfect time to do! It's very simple!, (*23)
# app/config/services.yml
services:
cache.app:
class: Symfony\Component\Cache\Adapter\FilesystemAdapter
# app/config/config.yml
lexxpavlov_settings:
cache_provider: cache.app
The bundle will use registered service cache.app for cache data. Cache provider may be one of
Doctrine cache or
Symfony cache - PSR-6 Cache (Symfony 3.1) or PSR-16 Simple Cache (Symfony 3.3)., (*24)
Arrange Settings admin group in SonataAdminBundle
SonataAdminBundle arranges admin groups by its bundles in AppKernel::registerBundles(). If LexxpavlovSettingsBundle
is added above your app bundles, then Settings group will be first group in menu (before your content or service groups,
created in your bundles). If you want that settings group will be last group (below your groups), you add
LexxpavlovSettingsBundle after your bundle in AppKernel::registerBundles():, (*25)
// app/AppKernel.php
public function registerBundles()
{
$bundles = array(
// ...
new AppBundle\AppBundle(),
new Lexxpavlov\SettingsBundle\LexxpavlovSettingsBundle(),
);
}
Manage settings without Sonata Admin
If you don't use SonataAdminBundle in your project, you may use predefined forms or special functions., (*26)
Save setting:, (*27)
$form = $this->createForm('lexxpavlov_settings');
// $form->setData($setting); // use for edit of existed setting
if ($request->isMethod('POST')) {
$form->handleRequest($request);
if ($form->isValid()) {
$this->get('settings')->save($form->getData());
}
}
return array( 'form' => $form->createView() );
Save group:, (*28)
$form = $this->createForm('lexxpavlov_settings_category');
if ($request->isMethod('POST')) {
$form->handleRequest($request);
if ($form->isValid()) {
$this->get('settings')->saveGroup($form->getData());
}
}
return array( 'form' => $form->createView() );
For use predefined forms, you need add form theme:, (*29)
# app/config/config.yml
twig:
# ...
form_themes:
- 'LexxpavlovSettingsBundle:Form:setting_value_edit.html.twig'
Manual create and update settings
use Lexxpavlov\SettingsBundle\DBAL\SettingsType;
// In controller:
// Get service from container
$settings = $this->get('settings');
// Update a existed setting
$settings->update('param', 'new value');
$settings->update('category', 'param_in_cat', 'new value');
// Create a new setting
$settings->create(null, 'new.1', SettingsType::Boolean, true, 'comment - setting w/o group');
$settings->create('test', 'new.2', SettingsType::Text, 'test text', 'comment - setting in group');
// Create a new empty group
$settings->createGroup('new-cat', 'comment of group');
Wallogit.com
