README

Are you often tired to repeat static choices like gender or civility in your apps ?

Requirements

• PHP >= 8.1
• Symfony 5.4, 6.4 or 7.*

Installation

Run the following command:

composer require knplabs/dictionary-bundle

Register the bundle in config/bundles.php

$bundles = array( // ... Knp\DictionaryBundle\KnpDictionaryBundle::class => ['all' => true], );

Maintainers

You can ping us if need some reviews/comments/help:

• @AntoineLelaisant
• @PedroTroller

Basic usage

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 retreive it by injecting the Collection service and accessing the dictionary by its key

 private Dictionary $myDictionary; public function __construct( \Knp\DictionaryBundle\Dictionary\Collection $dictionaries) { $this->myDictionary = $dictionaries['my_dictionary']; }

Dictionary form type

Now, use them in your forms:

use Knp\DictionaryBundle\Form\Type\DictionaryType; public function buildForm(FormBuilderInterface $builder, array $options) { $builder ->add('civility', DictionaryType::class, array( 'name' => 'my_dictionary' )) ; }

The dictionary form type extends the symfony's choice type and its options.

Validation constraint

You can also use the constraint for validation. The value has to be set.

use Knp\DictionaryBundle\Validator\Constraints\Dictionary; class User { /**  * @ORM\Column  * @Dictionary(name="my_dictionary")  */ private $civility; }

Advanced usage

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"

Available types

• value (default) : Natural indexation
• value_as_key: Keys are defined from their value
• key_value: Define your own keys
• callable: 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.

Iterator based dictionary

You can create a dictionary from an iterator:

knp_dictionary: dictionaries: my_iterator_dictionary: # your dictionary name type: 'iterator' # your dictionary type service: 'app.service.id' # a valid service from your application

Iterator based dictionaries are loaded with a lazy strategy. It means that the iterator will not be fetched if you do not use the dictionary.

Combined dictionary

You can combine multiple dictionaries into a single one:

knp_dictionary: dictionaries: payment_mode: type: key_value content: card: "credit card" none: "none" extra_payment_mode: type: key_value content: bank_transfer: "Bank transfer" other: "Other" combined_payment_mode: type: combined dictionaries: - payment_mode - extra_payment_mode

Now you have 3 dictionaries, payment_mode and extra_payment_mode contain their own values but combined_payment_mode contains all the values of the previous ones.

Extended dictionary

You can create an extended dictionary:

knp_dictionary: dictionaries: europe: type: 'key_value' content: fr: France de: Germany world: type: 'key_value' extends: europe content: us: USA ca: Canada

The dictionary world will now contain its own values in addition to the europe values.

Note: You must define the initial dictionary BEFORE the extended one.

Transformers

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 !

Add your own transformers

Create your class that implements TransformerInterface. Load your transformer and tag it as knp_dictionary.value_transformer.

services: App\My\Transformer: tags: - knp_dictionary.value_transformer

Use your dictionary in twig

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') }}

Faker provider

The KnpDictionaryBundle comes with a faker provider that can be used to provide a random entry from a dictionary.

Alice

To register the provider in nelmio/alice, you can follow the official documentation

App\Entity\User: john_doe: firstname: John latnale: Doe city: <dictionary('cities')>

Create your own dictionary implementation

Dictionary

Your dictionary implementation must implements the interface Dictionary.

It is automaticaly registered with the autoconfigure: true DIC feature.

Else you can register it by your self:

services: App\Dictionary\MyCustomDictionary: tags: - knp_dictionary.dictionary

Dictionary Factory

You must create a dictionary factory that will be responsible to instanciate your dictionary.

It is automaticaly registered with the autoconfigure: true DIC feature.

Else you can register it by your self:

services: App\Dictionary\Factory\MyCustomFactory: tags: - knp_dictionary.factory

Tests

phpspec

composer install vendor/bin/phpspec run

php-cs-fixer

composer install vendor/bin/php-cs-fixer fix

phpstan

First install phive.

Then...

phive install tools/phpstan process

rector (optional)

rector process --set php70 --set php71 --set php72 --set code-quality --set coding-style --set symfony34 --set twig240 --set psr-4 --set solid src/ spec/