{"id":15782373,"url":"https://github.com/knplabs/dictionarybundle","last_synced_at":"2025-04-05T09:07:00.139Z","repository":{"id":23598605,"uuid":"26967383","full_name":"KnpLabs/DictionaryBundle","owner":"KnpLabs","description":"Are you often tired to repeat static choices like gender or civility in your apps ?","archived":false,"fork":false,"pushed_at":"2024-05-29T00:10:21.000Z","size":458,"stargazers_count":86,"open_issues_count":6,"forks_count":24,"subscribers_count":22,"default_branch":"master","last_synced_at":"2024-05-29T04:11:33.176Z","etag":null,"topics":["hacktoberfest","php","symfony","symfony-bundle"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KnpLabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-11-21T16:18:37.000Z","updated_at":"2024-06-06T12:43:29.801Z","dependencies_parsed_at":"2023-11-27T17:30:21.200Z","dependency_job_id":"d2b84c7f-0521-4f2b-9556-80126000c55c","html_url":"https://github.com/KnpLabs/DictionaryBundle","commit_stats":{"total_commits":196,"total_committers":20,"mean_commits":9.8,"dds":0.5714285714285714,"last_synced_commit":"ead34f52336b13fcc2906ae67b16231c12cc984e"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KnpLabs%2FDictionaryBundle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KnpLabs%2FDictionaryBundle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KnpLabs%2FDictionaryBundle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KnpLabs%2FDictionaryBundle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KnpLabs","download_url":"https://codeload.github.com/KnpLabs/DictionaryBundle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247312078,"owners_count":20918344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","php","symfony","symfony-bundle"],"created_at":"2024-10-04T19:06:24.799Z","updated_at":"2025-04-05T09:07:00.097Z","avatar_url":"https://github.com/KnpLabs.png","language":"PHP","readme":"DictionaryBundle\n================\n[![CircleCI](https://circleci.com/gh/KnpLabs/DictionaryBundle.svg?style=svg)](https://circleci.com/gh/KnpLabs/DictionaryBundle)\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/KnpLabs/DictionaryBundle/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/KnpLabs/DictionaryBundle/?branch=master)\n\nAre you often tired to repeat static choices like gender or civility in your apps ?\n\n## Requirements\n\n- PHP \u003e= 8.1\n- Symfony 5.4, 6.4 or 7.*\n\n## Installation\n\nRun the following command:\n```bash\ncomposer require knplabs/dictionary-bundle\n```\nRegister the bundle in ``config/bundles.php``\n\n```php\n$bundles = array(\n    // ...\n    Knp\\DictionaryBundle\\KnpDictionaryBundle::class =\u003e ['all' =\u003e true],\n);\n```\n\n## Maintainers\n\nYou can ping us if need some reviews/comments/help:\n\n - [@AntoineLelaisant](https://github.com/AntoineLelaisant)\n - [@PedroTroller](https://github.com/PedroTroller)\n\n## Basic usage\n\nDefine dictionaries in your config.yml file:\n```yaml\nknp_dictionary:\n  dictionaries:\n    my_dictionary: # your dictionary name\n      - Foo        # your dictionary content\n      - Bar\n      - Baz\n```\nYou will be able to retreive it by injecting the Collection service and accessing the dictionary by its key\n```php\n\n    private Dictionary $myDictionary;\n    public function __construct(\n        \\Knp\\DictionaryBundle\\Dictionary\\Collection $dictionaries)\n    {\n        $this-\u003emyDictionary = $dictionaries['my_dictionary'];\n    }\n```\n### Dictionary form type\n\nNow, use them in your forms:\n\n```php\nuse Knp\\DictionaryBundle\\Form\\Type\\DictionaryType;\n\npublic function buildForm(FormBuilderInterface $builder, array $options)\n{\n    $builder\n        -\u003eadd('civility', DictionaryType::class, array(\n            'name' =\u003e 'my_dictionary'\n        ))\n    ;\n}\n```\nThe dictionary form type extends the [symfony's choice type](http://symfony.com/fr/doc/current/reference/forms/types/choice.html) and its options.\n\n### Validation constraint\n\nYou can also use the constraint for validation. The `value` has to be set.\n\n```php\nuse Knp\\DictionaryBundle\\Validator\\Constraints\\Dictionary;\n\nclass User\n{\n    /**\n     * @ORM\\Column\n     * @Dictionary(name=\"my_dictionary\")\n     */\n    private $civility;\n}\n```\n\n## Advanced usage\nYou can specify the indexation mode of each dictionary\n```yaml\nknp_dictionary:\n  dictionaries:\n    my_dictionary:      # your dictionary name\n      type: 'key_value' # your dictionary type\n      content:          # your dictionary content\n        \"foo\": \"foo_value\"\n        \"bar\": \"bar_value\"\n        \"baz\": \"baz_value\"\n```\n### Available types\n- `value` (default) : Natural indexation\n- `value_as_key`: Keys are defined from their value\n- `key_value`: Define your own keys\n- `callable`: Build a dictionary from a callable\n\n### Callable dictionary\nYou can create a callable dictionary:\n```yaml\nknp_dictionary:\n  dictionaries:\n    my_callable_dictionary:     # your dictionary name\n      type: 'callable'          # your dictionary type\n      service: 'app.service.id' # a valid service from your application\n      method: 'getSomething'    # the method name to execute\n```\nCallable dictionaries are loaded with a lazy strategy. It means that the callable\nwill not be called if you do not use the dictionary.\n\n### Iterator based dictionary\nYou can create a dictionary from an iterator:\n```yaml\nknp_dictionary:\n  dictionaries:\n    my_iterator_dictionary:     # your dictionary name\n      type: 'iterator'          # your dictionary type\n      service: 'app.service.id' # a valid service from your application\n```\nIterator based dictionaries are loaded with a lazy strategy. It means that the \niterator will not be fetched if you do not use the dictionary.\n\n### Combined dictionary\n\nYou can combine multiple dictionaries into a single one:\n```yaml\nknp_dictionary:\n  dictionaries:\n    payment_mode:\n      type: key_value\n      content:\n        card: \"credit card\"\n        none: \"none\"\n\n    extra_payment_mode:\n      type: key_value\n      content:\n        bank_transfer: \"Bank transfer\"\n        other: \"Other\"\n\n    combined_payment_mode:\n      type: combined\n      dictionaries:\n        - payment_mode\n        - extra_payment_mode\n```\nNow you have 3 dictionaries, `payment_mode` and `extra_payment_mode` contain \ntheir own values but `combined_payment_mode` contains all the values of the previous ones.\n\n### Extended dictionary\n\nYou can create an extended dictionary:\n```yaml\nknp_dictionary:\n  dictionaries:\n    europe:\n      type: 'key_value'\n      content:\n        fr: France\n        de: Germany\n\n    world:\n      type: 'key_value'\n      extends: europe\n      content:\n        us: USA\n        ca: Canada\n```\nThe dictionary `world` will now contain its own values in addition\nto the `europe` values.\n\n**Note**: You must define the initial dictionary **BEFORE** the extended one.\n\n## Transformers\nFor now, this bundle is only able to resolve your **class constants**:\n\n```yaml\nmy_dictionary:\n  - MyClass::MY_CONSTANT\n  - Foo\n  - Bar\n```\nYou want to add other kinds of transformations for your dictionary values ?\nFeel free to create your own transformer !\n\n### Add your own transformers\n\nCreate your class that implements [TransformerInterface](src/Knp/DictionaryBundle/Dictionary/ValueTransformer/TransformerInterface.php).\nLoad your transformer and tag it as `knp_dictionary.value_transformer`.\n```yaml\nservices:\n  App\\My\\Transformer:\n    tags:\n      - knp_dictionary.value_transformer\n```\n\n## Use your dictionary in twig\n\nYou can also use your dictionary in your Twig templates via calling `dictionary` function (or filter).\n\n```twig\n{% for example in dictionary('examples') %}\n    {{ example }}\n{% endfor %}\n```\n\nBut you can also access directly to a value by using the same function (or filter)\n\n```twig\n{{ 'my_key'|dictionary('dictionary_name') }}\n```\n\n## Faker provider\n\nThe KnpDictionaryBundle comes with a [faker provider](https://github.com/FakerPHP/Faker) that can be used to provide a random entry from a dictionary.\n\n### Alice\n\nTo register the provider in [nelmio/alice](https://github.com/nelmio/alice), you can follow the [official documentation](https://github.com/nelmio/alice/blob/master/doc/customizing-data-generation.md#add-a-custom-faker-provider-class)\n\n```yaml\nApp\\Entity\\User:\n  john_doe:\n    firstname: John\n    latnale: Doe\n    city: \u003cdictionary('cities')\u003e\n```\n\n## Create your own dictionary implementation\n\n### Dictionary\n\nYour dictionary implementation must implements the interface [Dictionary](src/Knp/DictionaryBundle/Dictionary.php).\n\nIt is automaticaly registered with the `autoconfigure: true` DIC feature.\n\nElse you can register it by your self: \n\n```yaml\nservices:\n  App\\Dictionary\\MyCustomDictionary:\n    tags:\n      - knp_dictionary.dictionary\n```\n\n### Dictionary Factory\n\nYou must create a dictionary factory that will be responsible to instanciate your dictionary.\n\nIt is automaticaly registered with the `autoconfigure: true` DIC feature.\n\nElse you can register it by your self: \n\n```yaml\nservices:\n  App\\Dictionary\\Factory\\MyCustomFactory:\n    tags:\n      - knp_dictionary.factory\n```\n## Tests\n\n### phpspec\n\n```bash\ncomposer install\nvendor/bin/phpspec run\n```\n\n### php-cs-fixer\n\n```bash\ncomposer install\nvendor/bin/php-cs-fixer fix\n```\n\n### phpstan\n\nFirst [install phive](https://github.com/phar-io/phive#getting-phive).\n\nThen...\n\n```bash\nphive install\ntools/phpstan process\n```\n\n### rector (*optional*)\n\n```bash\nrector process --set php70 --set php71 --set php72 --set code-quality --set coding-style --set symfony34 --set twig240 --set psr-4 --set solid src/ spec/\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknplabs%2Fdictionarybundle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknplabs%2Fdictionarybundle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknplabs%2Fdictionarybundle/lists"}