Tag Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require coosos/tag-bundle
   

   Ensure your composer.json includes the bundle in require.

2. Enable the Bundle: Add to config/bundles.php (Symfony 4+):

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

3. Create Tag Entity: Run the migration to generate the Tag table:

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

4. First Use Case: Use the TagType form field in a Symfony form:

   use Coosos\TagBundle\Form\Type\TagType;
   
   $builder->add('tags', TagType::class, [
       'multiple' => true,
       'label' => 'Tags',
   ]);
   

Implementation Patterns

Common Workflows

1. Basic Tagging in Forms: Attach TagType to any entity form for tagging functionality:

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

2. Customizing Tag Behavior: Override the default Tag entity (extend Coosos\TagBundle\Entity\Tag):

   namespace App\Entity;
   
   use Coosos\TagBundle\Entity\Tag as BaseTag;
   
   class Tag extends BaseTag
   {
       // Add custom fields/methods
   }
   

3. Integration with Entities: Use @ManyToMany in your entity to link tags:

   /**
    * @ORM\ManyToMany(targetEntity="Coosos\TagBundle\Entity\Tag")
    */
   private $tags;
   

4. Frontend Integration:

   • Include jQuery and jquery.tagEditor for rich tagging UI:

     <link rel="stylesheet" href="path/to/jquery.tagEditor.css">
     <script src="path/to/jquery.tagEditor.js"></script>
     

   • Initialize in Twig:

     {{ form_widget(form.tags, {'attr': {'class': 'tag-editor'}}) }}
     <script>
         $('.tag-editor').tagEditor();
     </script>
     

5. API/REST Usage: Expose tag endpoints via API Platform or custom controllers:

   // Example: Fetch tags for autocomplete
   $tags = $this->getDoctrine()->getRepository(Tag::class)->findByName($query);
   

Gotchas and Tips

Pitfalls

1. Outdated Dependencies:

   • Last release in 2018 may cause compatibility issues with newer Symfony/PHP versions.
   • Test thoroughly with Symfony 5/6; may require patches or forks.

2. Missing Doctrine Configuration:

   • Ensure Coosos\TagBundle\Entity\Tag is mapped in config/packages/doctrine.yaml:

     orm:
         mappings:
             coosos_tag:
                 type: attribute
                 dir: "%kernel.project_dir%/vendor/coosos/tag-bundle/Entity"
                 prefix: "Coosos\TagBundle\Entity"
                 alias: CoososTagBundle
     

3. Frontend Assets:

   • jQuery plugins (tagEditor, autocomplete) are optional but required for full functionality.
   • Verify paths to JS/CSS in your bundle’s assets (may need manual inclusion).

4. Tag Uniqueness:

   • The bundle assumes tags are case-sensitive by default. Add a unique constraint in Tag entity if needed:

     /**
      * @ORM\Column(unique=true)
      */
     private $name;
     

Debugging Tips

1. Check Database Schema: Run php bin/console doctrine:schema:validate to ensure the Tag table is correctly created.

2. Form Submission Issues:

   • Validate form data manually if tags fail to save:

     $form->handleRequest($request);
     if ($form->isSubmitted() && $form->isValid()) {
         $entity->getTags()->clear(); // Clear existing tags if needed
         $entity->addTag($form->get('tags')->getData());
     }
     

3. Autocomplete Not Working:

   • Ensure jQuery UI is loaded before jquery.tagEditor.
   • Check browser console for 404 errors on JS/CSS files.

Extension Points

1. Custom Tag Repository: Extend Coosos\TagBundle\Repository\TagRepository to add query methods:

   namespace App\Repository;
   
   use Coosos\TagBundle\Repository\TagRepository as BaseTagRepository;
   
   class TagRepository extends BaseTagRepository
   {
       public function findPopularTags(int $limit = 10)
       {
           return $this->createQueryBuilder('t')
               ->orderBy('t.usageCount', 'DESC')
               ->setMaxResults($limit)
               ->getQuery()
               ->getResult();
       }
   }
   

2. Event Listeners: Attach listeners to Tag events (e.g., prePersist):

   namespace App\EventListener;
   
   use Coosos\TagBundle\Entity\Tag;
   use Doctrine\Common\EventSubscriber;
   use Doctrine\ORM\Event\LifecycleEventArgs;
   
   class TagListener implements EventSubscriber
   {
       public function getSubscribedEvents()
       {
           return ['prePersist'];
       }
   
       public function prePersist(Tag $tag, LifecycleEventArgs $args)
       {
           $tag->setSlug(strtolower($tag->getName()));
       }
   }
   

3. Override Twig Templates: Copy templates from vendor/coosos/tag-bundle/Resources/views/ to templates/coosos_tag/ to customize rendering.

4. Symfony 5+ Flex Integration: If using Symfony Flex, manually register the bundle in config/bundles.php (no AppKernel.php in Flex).