Tag Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require beelab/tag-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       BeeLab\TagBundle\BeeLabTagBundle::class => ['all' => true],
   ];
   

2. Database Migration: Run migrations to create the tag and taggable tables:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

3. First Use Case: Tag an entity (e.g., Article) by implementing TaggableInterface:

   use BeeLab\TagBundle\Model\TaggableInterface;
   
   class Article implements TaggableInterface
   {
       // ...
   }
   

   Use the TagManager to add tags:

   $article = new Article();
   $tagManager = $this->get('bee_lab_tag.tag_manager');
   $tagManager->tag($article, ['laravel', 'symfony', 'php']);
   

Implementation Patterns

Common Workflows

1. Tagging Entities:

   // Add tags to an entity
   $tagManager->tag($entity, ['tag1', 'tag2']);
   
   // Remove tags from an entity
   $tagManager->untag($entity, ['tag1']);
   

2. Querying Tagged Entities: Use the TagRepository to fetch entities by tags:

   $tagRepository = $this->get('bee_lab_tag.tag_repository');
   $articles = $tagRepository->findByTag('laravel', Article::class);
   

3. Tag Autocomplete: Use the TagAutocomplete service for frontend tag suggestions:

   $autocomplete = $this->get('bee_lab_tag.tag_autocomplete');
   $suggestions = $autocomplete->getSuggestions('lar', 5);
   

4. Custom Tagging Logic: Extend the TagManager or create a custom service to handle business-specific tagging rules.

Integration Tips

• Forms: Use the BeeLabTagBundle\Form\Type\TagType for easy tag input in Symfony forms:

  $builder->add('tags', TagType::class, [
      'multiple' => true,
      'label' => 'Tags',
  ]);
  

• APIs: Expose tagging endpoints (e.g., /articles/{id}/tags) using Symfony’s serializer:

  use BeeLab\TagBundle\Serializer\TagNormalizer;
  
  // Register the normalizer in your API platform config
  

• Event Listeners: Trigger actions when tags are added/removed (e.g., update search indexes):

  // In services.yaml
  bee_lab_tag.tag_manager:
      tags: [doctrine.event_listener, kernel.event_listener]
  

Gotchas and Tips

Pitfalls

1. Circular References: Avoid circular references in tagged entities (e.g., Article tagged with Category, which is also tagged with Article). Use @ORM\ManyToMany carefully.

2. Performance: Fetching all tagged entities for a tag can be slow for large datasets. Use pagination:

   $articles = $tagRepository->findByTag('laravel', Article::class, 1, 10);
   

3. Case Sensitivity: Tags are case-sensitive by default. Normalize tags (e.g., strtolower()) if case-insensitive behavior is needed.

4. Duplicate Tags: The bundle does not enforce uniqueness. Handle duplicates in your application logic or via database constraints.

Debugging

• Tag Not Found: Ensure the Tag entity is properly mapped in Doctrine and the taggable table exists.

• No Tags Persisted: Verify the TagManager is injected correctly and the entity implements TaggableInterface.

• Query Issues: Use dd() or var_dump() to inspect the TagRepository methods and their return types.

Extension Points

1. Custom Tag Storage: Override the TagStorage service to use a different storage backend (e.g., Redis).

2. Tag Validation: Extend the TagValidator to enforce custom rules (e.g., max length, allowed characters).

3. Tag Events: Dispatch custom events when tags are added/removed:

   // In your event subscriber
   $eventDispatcher->dispatch(new TagAddedEvent($entity, $tags));
   

4. Translation: Use Symfony’s translation system to localize tag names or descriptions.

Configuration Quirks

• Default Tag Class: Override the default Tag entity class in config/packages/bee_lab_tag.yaml:

  bee_lab_tag:
      tag_entity: App\Entity\CustomTag
  

• Taggable Entities: Ensure all tagged entities implement TaggableInterface and have the correct ManyToMany association.

• Caching: Clear the cache after modifying bundle configurations:

  php bin/console cache:clear