Dictionary Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require biig/dictionary-bundle
   

   Ensure your AppKernel.php includes:

   new Knp\DictionaryBundle\KnpDictionaryBundle(),
   

2. Define a Dictionary: Add a dictionary to config/packages/knp_dictionary.yaml:

   knp_dictionary:
       dictionaries:
           gender:
               - { value: 'male', label: 'Male' }
               - { value: 'female', label: 'Female' }
               - { value: 'other', label: 'Other' }
   

3. First Use Case: Retrieve the dictionary in a controller/service:

   use Knp\DictionaryBundle\Registry\DictionaryRegistryInterface;
   
   public function __construct(DictionaryRegistryInterface $dictionaryRegistry) {
       $this->dictionaryRegistry = $dictionaryRegistry;
   }
   
   public function someAction() {
       $genderDict = $this->dictionaryRegistry->get('gender');
       $maleLabel = $genderDict->getLabel('male'); // Returns 'Male'
   }
   

Implementation Patterns

Common Workflows

1. Dictionary Definition:

   • Use YAML for static dictionaries (e.g., gender, status).
   • For dynamic dictionaries, extend Knp\DictionaryBundle\Dictionary\AbstractDictionary and register via services.

2. Integration with Forms:

   use Knp\DictionaryBundle\Form\Type\DictionaryType;
   
   $builder->add('status', DictionaryType::class, [
       'dictionary' => 'order_status',
       'expanded' => true,
       'multiple' => false,
   ]);
   

3. Translation Support: Define labels in translation files (e.g., translations/messages.en.yaml):

   gender:
       male: 'Mr.'
       female: 'Ms.'
       other: 'Other'
   

   Then reference in YAML:

   gender:
       - { value: 'male', label: 'gender.male' }
   

4. Dependency Injection: Inject DictionaryRegistryInterface into services/controllers to reuse dictionaries across the app.

Advanced Patterns

• Dynamic Dictionaries: Create a custom dictionary service and register it programmatically:

  services:
      app.custom_dictionary:
          class: App\Dictionary\CustomDictionary
          tags: ['knp_dictionary.dictionary']
  

• Validation Constraints: Use dictionaries in validation rules:

  use Knp\DictionaryBundle\Validator\Constraints\Dictionary;
  
  /**
   * @Assert\IsTrue(message="Invalid status.")
   * @Assert\Dictionary(dictionary="order_status")
   */
  private $status;
  

Gotchas and Tips

Pitfalls

1. Branch Confusion: The package is actively maintained on the 3.x branch (not the default master). Ensure you reference the correct branch in docs/installation.

2. YAML Parsing Quirks:

   • Values must be strings (e.g., 'male' not male).
   • Labels support translation keys (e.g., label: 'gender.male').
   • Avoid special characters in dictionary keys (e.g., order-status may cause issues; use order_status instead).

3. Caching: Dictionaries are cached by default. Clear the cache (php bin/console cache:clear) after changes to config/knp_dictionary.yaml.

4. Symfony 5+ Compatibility: The bundle is designed for Symfony 3.4+. For Symfony 5+, ensure AppKernel.php is updated to config/bundles.php if migrating.

Debugging Tips

• Check Registered Dictionaries:

  $this->dictionaryRegistry->getAvailableDictionaries(); // Lists all loaded dictionaries.
  

• Validate YAML: Use php bin/console debug:config knp_dictionary to verify dictionary structure.

Extension Points

1. Custom Dictionary Classes: Extend AbstractDictionary to add logic (e.g., database-backed dictionaries):

   class DbDictionary extends AbstractDictionary {
       public function getItems() {
           return $this->entityManager->getRepository(MyEntity::class)->findAll();
       }
   }
   

2. Override Default Templates: The bundle uses Twig templates for rendering (e.g., dictionary_select.html.twig). Override them in your theme.

3. Event Listeners: Listen to knp_dictionary.dictionary.load to modify dictionaries at runtime:

   services:
       app.dictionary_listener:
           class: App\EventListener\DictionaryListener
           tags:
               - { name: kernel.event_listener, event: knp_dictionary.dictionary.load, method: onLoad }