Classification Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require sonata-project/classification-bundle
   

   Enable it in config/bundle.php:

   return [
       // ...
       Sonata\ClassificationBundle\SonataClassificationBundle::class => ['all' => true],
   ];
   

2. Database Migrations Run the provided migrations (located in vendor/sonata-project/classification-bundle/migrations) to create tables for:

   • SonataClassificationNode (taxonomy nodes)
   • SonataClassificationNodeTranslation (translations)
   • SonataClassificationNodeHierarchy (hierarchy relationships)

3. First Use Case: Basic Taxonomy Define a taxonomy in a Doctrine entity (e.g., ProductCategory):

   use Sonata\ClassificationBundle\Model\ClassificationNodeInterface;
   
   /**
    * @ORM\Entity
    */
   class ProductCategory implements ClassificationNodeInterface
   {
       // Implement required methods from ClassificationNodeInterface
       // ...
   }
   

4. Admin Configuration Register the admin class in config/packages/sonata_admin.yaml:

   sonata_admin:
       options:
           models:
               ProductCategory: App\Entity\ProductCategory
   

Implementation Patterns

Workflows

1. Creating a Taxonomy

   • Use the Sonata Admin interface to create a root node (e.g., "Categories").
   • Add child nodes (e.g., "Electronics", "Clothing") via drag-and-drop hierarchy.
   • Translate nodes for multilingual support.

2. Assigning Taxonomies to Entities Link entities (e.g., Product) to taxonomy nodes via a many-to-many relationship:

   /**
    * @ORM\ManyToMany(targetEntity="ProductCategory")
    * @ORM\JoinTable(name="product_category")
    */
   private $categories;
   

3. Querying by Taxonomy Fetch products under a specific category:

   $products = $entityManager->getRepository(Product::class)
       ->findBy(['categories' => $categoryNode]);
   

4. Dynamic Taxonomy Rendering Use Twig to display taxonomy paths:

   {% for node in product.categories %}
       {{ node.getPathAsString() }} →
   {% endfor %}
   

Integration Tips

• Custom Fields: Extend Sonata\ClassificationBundle\Form\Type\ClassificationNodeType to add custom validation or fields.
• API Exposure: Use Symfony’s serializers to expose taxonomy data in APIs:

  use Sonata\ClassificationBundle\Serializer\ClassificationNodeNormalizer;
  
  $serializer->normalize($node, null, [
      new ClassificationNodeNormalizer(),
  ]);
  

• Event Listeners: Subscribe to sonata.classification.node.pre_persist or sonata.classification.node.pre_update to modify nodes before saving.

Gotchas and Tips

Pitfalls

1. Hierarchy Depth Limits

   • Default recursion depth for getPath() is 10. Increase via:

     $node->setMaxDepth(20);
     

   • Deep hierarchies may cause performance issues; optimize with database indexes.

2. Translation Conflicts

   • Ensure sonata_classification_node_translation table has unique constraints on (node_id, locale).
   • Clear cache after bulk translations:

     php bin/console cache:clear
     

3. Admin Route Conflicts

   • Sonata’s admin routes may clash with custom routes. Override in config/routes.yaml:

     sonata_classification:
         resource: '@SonataClassificationBundle/Resources/config/routing/admin.xml'
         prefix: /admin/classification
     

4. Lazy-Loading Issues

   • Eager-load related nodes to avoid N+1 queries:

     $query->leftJoin('node.children', 'children')
           ->addSelect('children');
     

Debugging

• Enable Debug Mode: Add to config/packages/dev/sonata_classification.yaml:

  sonata_classification:
      debug: true
  

  Logs hierarchy operations to var/log/dev.log.

• Check Node States:

  $node->isRoot();       // Is this the root node?
  $node->isLeaf();       // Has no children?
  $node->getParent();    // Get parent node.
  

Extension Points

1. Custom Node Types Extend Sonata\ClassificationBundle\Model\ClassificationNode to add custom logic:

   class CustomNode extends ClassificationNode
   {
       private $customField;
   
       // Add getters/setters and override methods as needed.
   }
   

2. Override Templates Copy templates from vendor/sonata-project/classification-bundle/Resources/views to templates/SonataClassificationBundle to customize admin UI.

3. Add Validation Use Symfony’s constraints on taxonomy nodes:

   use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;
   
   /**
    * @UniqueEntity(fields={"name", "locale"}, message="Duplicate node name.")
    */
   class ProductCategory implements ClassificationNodeInterface
   {
       // ...
   }