Labels Bundle Laravel Package

Getting Started

1. Installation:

   • Require the bundle via Composer: composer require astina/labels-bundle.
   • Register AstinaLabelsBundle and StofDoctrineExtensionsBundle in AppKernel.php.
   • Configure stof_doctrine_extensions in config.yml to enable translatable entities.

2. First Use Case:

   • Add a labels property to a Doctrine entity (e.g., Product):

     /**
      * @ORM\ManyToMany(targetEntity="Astina\Bundle\LabelsBundle\Entity\Label")
      */
     private $labels;
     

   • Set up fixtures to populate LabelCategory and Label entities (e.g., via DoctrineFixturesBundle).

3. Quick Form Integration:

   • Use the astina_labels form type in a form builder:

     $builder->add('labels', 'astina_labels', [
         'categories' => ['color', 'size'],
         'label' => 'Filters',
         'required' => false,
     ]);
     

Implementation Patterns

Entity Labeling

• Workflow:

  1. Define a ManyToMany relationship between your entity and Astina\Bundle\LabelsBundle\Entity\Label.
  2. Use fixtures or admin panels (e.g., SonataAdmin) to seed LabelCategory and Label entities.
  3. Assign labels to entities via:

     $product->addLabel($label);
     $entityManager->persist($product);
     

• Translations:

  • Leverage Gedmo\Translatable for multilingual labels (configured via stof_doctrine_extensions).
  • Example translation entity:

    /**
     * @Gedmo\TranslationEntity(class="Astina\Bundle\LabelsBundle\Entity\LabelTranslation")
     */
    class Label {}
    

Form Integration

• Dynamic Filtering:
  • Use the astina_labels field type to render checkboxes/radio buttons for each category.
  • Pass categories to restrict displayed labels (e.g., ['color', 'material']).
  • Example with validation:

    $builder->add('labels', 'astina_labels', [
        'categories' => ['color'],
        'label' => 'Select Colors',
        'required' => false,
        'multiple' => true,
    ]);
    

Search Integration

• Service Configuration:

  • Define a search service in services.yml:

    app.filter_search.product:
        class: Astina\Bundle\LabelsBundle\Search\LabelSearch
        arguments:
            - @astina_labels.repository.label
            - @app.repository.product
    

  • Use TranslatedLabelSearch for multilingual support.

• Querying:

  • Inject the service and search by labels:

    $search = $container->get('app.filter_search.product');
    $results = $search->search(new \Astina\Bundle\LabelsBundle\Search\SearchQuery(['red', 'blue']));
    

Admin Panels

• SonataAdmin Integration:
  • Extend Sonata\AdminBundle\Admin\Admin to add label management:

    protected function configureFormFields(FormMapper $formMapper) {
        $formMapper->add('labels', 'astina_labels', [
            'categories' => ['color', 'size'],
        ]);
    }
    

Gotchas and Tips

Pitfalls

1. Missing Fixtures:

   • Labels won’t appear in forms without pre-populated LabelCategory and Label entities.
   • Fix: Use DoctrineFixturesBundle or a custom CLI command to seed data.

2. Translations Not Working:

   • Ensure stof_doctrine_extensions is configured with translatable: true and default_locale set.
   • Fix: Clear cache (php bin/console cache:clear) after enabling translations.

3. Form Field Not Rendering:

   • If categories aren’t passed to the form type, no labels will display.
   • Fix: Always specify categories in the form builder.

4. Deprecated Symfony Version:

   • The bundle targets Symfony 2.3–2.7. For Symfony 3+/4+, consider forking or using alternatives like FOSCKEditorBundle for label-like functionality.

Debugging

• Empty Search Results:

  • Verify the SearchQuery contains valid label names (case-sensitive).
  • Check if labels are correctly linked to entities via ManyToMany.

• Translation Domain Issues:

  • For Symfony 2.7+, ensure choice_translation_domain is set in the form type (handled in v0.4.0).

Extension Points

1. Custom Label Priorities:

   • Use the priority property in Label to sort labels (added in v0.3.0):

     $label->setPriority(1); // Lower numbers appear first
     

2. Override Search Logic:

   • Extend Astina\Bundle\LabelsBundle\Search\LabelSearch to customize query building.

3. Add New Label Types:

   • Create a new entity (e.g., Tag) and replicate the Label structure for reuse.

Performance Tips

• Index Labels:

  • Add database indexes to label and label_category tables for faster searches:

    CREATE INDEX idx_label_name ON label(name);
    CREATE INDEX idx_entity_labels ON entity_labels(entity_id, label_id);
    

• Cache Search Results:

  • Cache the LabelSearch service output if labels change infrequently:

    services:
        app.filter_search.product:
            class: Astina\Bundle\LabelsBundle\Search\LabelSearch
            arguments:
                - @astina_labels.repository.label
                - @app.repository.product
            calls:
                - [setCache, ['@cache.app']]