Taggable Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require anh/taggable-bundle:~1.0
   

   Enable the bundle in config/bundles.php:

   Anh\TaggableBundle\AnhTaggableBundle::class => ['all' => true],
   

2. Install Dependencies:

   php bin/console sp:bower:install
   

   Ensure bower is installed globally.

3. Update Doctrine Schema:

   php bin/console doctrine:schema:update --force
   

4. First Use Case: Add a tags field to an entity form:

   // src/Form/YourEntityType.php
   public function buildForm(FormBuilderInterface $builder, array $options)
   {
       $builder->add('tags', 'tags', [
           'tagit' => [], // Optional Tag-it options
           'autocomplete' => 'dynamic' // Default
       ]);
   }
   

Implementation Patterns

Common Workflows

1. Dynamic Tagging: Use autocomplete: 'dynamic' for real-time tag suggestions via AJAX. Customize the endpoint in ['tagit']['autocomplete']['source']:

   $builder->add('tags', 'tags', [
       'tagit' => [
           'autocomplete' => [
               'source' => '/api/tags/search'
           ]
       ]
   ]);
   

2. Static Tagging: Use autocomplete: 'static' for predefined tags (limited to 100):

   $builder->add('tags', 'tags', [
       'autocomplete' => 'static',
       'tagit' => [
           'availableTags' => ['php', 'laravel', 'symfony']
       ]
   ]);
   

3. Custom Tag Lists: Use autocomplete: 'custom' to bypass database fetching:

   $builder->add('tags', 'tags', [
       'autocomplete' => 'custom',
       'tagit' => [
           'availableTags' => ['backend', 'frontend']
       ]
   ]);
   

4. Tag-it Configuration: Pass options directly to the Tag-it library:

   $builder->add('tags', 'tags', [
       'tagit' => [
           'allowSpaces' => true,
           'caseSensitive' => false
       ]
   ]);
   

Integration Tips

• Twig Rendering: Include assets in your base template:

  {% stylesheets '@anh_taggable_css' %}
      <link rel="stylesheet" href="{{ asset_url }}">
  {% endstylesheets %}
  {% javascripts '@anh_taggable_js' %}
      <script src="{{ asset_url }}"></script>
  {% endjavascripts %}
  

• API Endpoint for Dynamic Tags: Create a controller to fetch tags dynamically:

  // src/Controller/TagController.php
  public function search(Request $request)
  {
      $query = $request->query->get('q');
      $tags = $this->getDoctrine()
          ->getRepository(Tag::class)
          ->findByName($query, 10); // Limit to 10 results
      return new JsonResponse(array_map(fn($tag) => $tag->getName(), $tags));
  }
  

• Entity Mapping: Ensure your entity uses the Taggable trait:

  use Gedmo\Mapping\Annotation as Gedmo;
  
  /**
   * @Gedmo\Taggable
   */
  class YourEntity
  {
      // ...
  }
  

Gotchas and Tips

Pitfalls

1. Schema Update Required: Forgetting to run doctrine:schema:update will cause Tag and Tagging tables to be missing, leading to runtime errors.

2. Bower Dependency: The bundle relies on SpBowerBundle. If bower is not installed globally, the assets won’t load. Install it with:

   npm install -g bower
   

3. Tag Limit: Both dynamic and static autocompletes are limited to 100 tags. Exceeding this may break functionality.

4. Mapping Override: If you manually define Tag or Tagging entities, disable the bundle’s auto-mapping in config/packages/doctrine.yaml:

   doctrine:
       orm:
           mappings:
               anh_taggable: { mapping: false }
   

5. JQueryUI Dependency: The bundle requires jQueryUI (v1.10.4). Ensure it’s loaded before the bundle’s JS:

   <script src="//ajax.googleapis.com/ajax/libs/jqueryui/1.10.4/jquery-ui.min.js"></script>
   

Debugging

• No Tags Appearing? Check if the AJAX endpoint (/api/tags/search by default) returns valid JSON. Use browser dev tools to inspect the network request.

• Form Not Rendering? Verify the anh_taggable_css and anh_taggable_js assets are correctly referenced in Twig. Clear cache if needed:

  php bin/console cache:clear
  

• Duplicate Tags: Ensure your Tag entity has a unique constraint on the name field (handled by default in the bundle’s schema).

Extension Points

1. Custom Tag Repository: Override the default tag repository to add custom logic (e.g., filtering):

   // src/Repository/CustomTagRepository.php
   class CustomTagRepository extends ServiceEntityRepository
   {
       public function findByName($name, $limit = 10, array $options = [])
       {
           // Custom logic here
       }
   }
   

   Update the service configuration to use your repository.

2. Tag-it Plugins: Extend the Tag-it widget with custom plugins by including additional JS/CSS and configuring the tagit options:

   $builder->add('tags', 'tags', [
       'tagit' => [
           'plugins' => ['your_plugin']
       ]
   ]);
   

3. Validation: Add validation rules for tags in your entity:

   use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;
   
   /**
    * @UniqueEntity(fields="tags", message="Tag already exists.")
    */
   class YourEntity
   {
       // ...
   }