knplabs / dictionary-bundle
Are you often tired to repeat static choices like gender or civility in your apps ?
Installs: 257 354
Dependents: 1
Suggesters: 0
Security: 0
Stars: 86
Watchers: 22
Forks: 24
Open Issues: 8
Type:symfony-bundle
Requires
- php: >=8.1
- symfony/config: ^5.4 || ^6.4 || ^7.0@dev
- symfony/dependency-injection: ^5.4 || ^6.4 || ^7.0@dev
- symfony/form: ^5.4 || ^6.4 || ^7.0@dev
- symfony/http-foundation: ^5.4 || ^6.4 || ^7.0@dev
- symfony/http-kernel: ^5.4 || ^6.4 || ^7.0@dev
- symfony/validator: ^5.4 || ^6.4 || ^7.0@dev
- twig/twig: ^2.15.3 || ^3.4.3
Requires (Dev)
- fakerphp/faker: 1.23.1
- friends-of-phpspec/phpspec-code-coverage: 6.3.0
- friendsofphp/php-cs-fixer: 3.49.0
- pedrotroller/php-cs-custom-fixer: 2.33.0
- phpspec/phpspec: 7.5.0
- phpspec/prophecy: 1.18.0
- phpstan/phpstan: 1.10.59
- rector/rector: 1.0.1
- symfony/twig-bridge: ^5.4 || ^6.4 || ^7.0@dev
- symfony/var-dumper: ^5.4 || ^6.4 || ^7.0@dev
- webmozart/assert: 1.11.0
- dev-master / 3.5.x-dev
- v3.5.0
- v3.4.0
- v3.3.1
- v3.3.0
- v3.2.0
- v3.1.3
- v3.1.2
- v3.1.1
- v3.1.0
- v3.0.0
- v2.3.0
- v2.2.0
- v2.1.1
- v2.1.0
- v2.0.3
- v2.0.2
- v2.0.1
- v2.0
- v1.5.2
- v1.5.1
- v1.5.0
- v1.4.1
- v1.4.0
- v1.3.1
- v1.3.0
- v1.2.0
- v1.1.1
- v1.1.0
- v1.0.0
- dev-dependabot/composer/phpstan/phpstan-1.12.1
- dev-dependabot/composer/friendsofphp/php-cs-fixer-3.64.0
- dev-dependabot/composer/friends-of-phpspec/phpspec-code-coverage-6.4.1
- dev-dependabot/composer/rector/rector-1.2.2
- dev-rel/php83-symfony7
- dev-refactor/phpstan-max
- dev-release
- dev-refactor/circleci-config
This package is auto-updated.
Last update: 2024-11-04 01:13:26 UTC
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:
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 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.
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/