Are you often tired to repeat static choices like gender or civility in your apps ?
This bundle is a fork. The motivation for forking it is the following:
- Getting a stable release (2.0)
- Adding Symfony 4 compatibility
- Ensure a future maintenance of the project
As today we still hope that the main project will reborn. There is also a lot of work to achieve to release all unreleased features.
That's why to install this fork you need to add the following lines to your composer.json
file.
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/biig-io/DictionaryBundle"
}
]
}
- Symfony >= 2.8
Add the DictionaryBundle to your composer.json
:
{
"require": {
"knplabs/dictionary-bundle": "~2.0"
}
}
Register the bundle in app/AppKernel.php
$bundles = array(
// ...
new Knp\DictionaryBundle\KnpDictionaryBundle(),
);
You can ping us if you need some reviews/comments/help:
Define dictionaries in your config.yml file:
knp_dictionary:
dictionaries:
my_dictionary: # your dictionary name
- Foo # your dictionary content
- Bar
- Baz
You will be able to retrieve it through the dictionary registry service:
$container->get('knp_dictionary.registry')->get('my_dictionary');
Now, use them in your forms:
use Knp\DictionaryBundle\Form\Type\DictionaryType;
public function buildForm(FormBuilderInterface $builder, array $options)
{
$builder
// PHP ~5.5.9 syntax
->add('civility', DictionaryType::class, array(
'name' => 'my_dictionary'
))
// PHP ~5.3.9+ syntax
->add('civility', 'Knp\DictionaryBundle\Form\Type\DictionaryType', array(
'name' => 'my_dictionary'
))
// PHP ~5.3.9+ (deprecated since Symfony 3.0)
->add('civility', 'dictionary', array(
'name' => 'my_dictionary'
))
;
}
The dictionary form type extends the symfony's choice type and its options.
You can also use the constraint for validation. The value
have to be set.
use Knp\DictionaryBundle\Validator\Constraints\Dictionary;
class User
{
/**
* @ORM\Column
* @Dictionary(name="my_dictionary")
*/
private $civility;
}
You can specify the indexation mode of each dictionary
knp_dictionary:
dictionaries:
my_dictionary: # your dictionary name
type: 'key_value' # your dictionary type
content: # your dictionary content
"foo": "foo_value"
"bar": "bar_value"
"baz": "baz_value"
value
(default) : Natural indexationvalue_as_key
: Keys are defined from their valuekey_value
: Define your own keyscallable
: Build a dictionary from a callable
### Callable dictionary You can create a callable dictionary:
knp_dictionary:
dictionaries:
my_callable_dictionary: # your dictionary name
type: 'callable' # your dictionary type
service: 'app.service.id' # a valid service from your application
method: 'getSomething' # the method name to execute
Callable dictionaries are loaded with a lazy strategy. It means that the callable will not be called if you do not use the dictionary.
For now, this bundle is only able to resolve your class constants:
my_dictionary:
- MyClass::MY_CONSTANT
- Foo
- Bar
You want to add other kinds of transformations for your dictionary values ? Feel free to create your own transformer !
Create your class that implements TransformerInterface.
Load your transformer and tag it as knp_dictionary.value_transformer
.
services:
my_bundle.my_namespace.my_transformer:
class: %my_transformer_class%
tags:
- { name: knp_dictionary.value_transformer }
You can also use your dictionary in your Twig templates via calling dictionary
function (or filter)
{% for example in dictionary('examples') %}
{{ example }}
{% endfor %}
But you can also access directly to a value by using the same function (or filter)
{{ 'my_key'|dictionary('dictionary_name') }}
The KnpDictionaryBundle comes with a faker provider that can be used to provide a random entry from a dictionary.
To register the provider in nelmio/alice, you can follow the official documentation
or ...
if you use the awesome knplabs/rad-fixtures-load library, the dictionary provider will be automaticaly loaded for you :)
App\Entity\User:
john_doe:
firstname: John
latnale: Doe
city: <dictionary('cities')>
## Create your own dictionary implementation
Your dictionary implementation must implements the interface Dictionary.
### Dictionary Factory You must create a dictionary factory that will be responsible to instanciate your dictionary.
services:
app.dictionary.factory.my_custom_factory:
class: App\Dictionary\Factory\MyCustomFactory
tags:
{ name: 'knp_dictionary.factory' }