Phpcr Taxonomy Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dantleech/phpcr-taxonomy-bundle
   

   Add to your AppKernel.php (or bundles.php for Symfony 5+):

   new DTL\PhpcrTaxonomyBundle\PhpcrTaxonomyBundle(),
   

2. Configure Taxonomy Paths: Define paths in config/packages/phpcr_taxonomy.yaml:

   dantleech_phpcr_taxonomy:
       taxonomies:
           tags: /var/www/data/tags
           categories: /var/www/data/categories
   

3. Annotate Your Document: Add @Taxons (string array) and @TaxonObjects (collection) to your PHPCR document:

   use DTL\PhpcrTaxonomyBundle\Metadata\Annotations as Taxonomy;
   
   /**
    * @Taxonomy\Taxons()
    * @Taxonomy\TaxonObjects()
    */
   class Article
   {
       // ...
   }
   

4. First Use Case: Tag a document via repository:

   $article = new Article();
   $article->setTaxons(['laravel', 'phpcr']);
   $dm->persist($article);
   $dm->flush();
   

Implementation Patterns

Workflow: Tagging Documents

1. Tag Assignment: Use setTaxons() to assign tags (creates missing taxons automatically):

   $post->setTaxons(['symfony', 'phpcr', 'taxonomy']);
   

2. Bulk Operations: Use the TaxonManager service to manage taxonomies:

   $taxonManager = $container->get('dantleech_phpcr_taxonomy.manager.taxon');
   $taxonManager->getTaxon('/var/www/data/tags/laravel');
   

3. Referrer Counts: Initialize counts via CLI:

   php bin/console dantleech:phpcr-taxonomy:fix-referrer-counts
   

4. Querying by Taxon: Use PHPCR queries with TaxonObjects:

   $qb = $dm->createQueryBuilder('Article');
   $qb->where($qb->expr()->in('taxonObjects', $taxon));
   

Integration Tips

• Event Listeners: Extend taxonomy behavior via TaxonEvents:

  $dispatcher->addListener(TaxonEvents::POST_CREATE, function ($taxon) {
      // Custom logic on taxon creation
  });
  

• Custom Taxon Types: Subclass Taxon to add fields:

  class CustomTaxon extends Taxon
  {
      /**
       * @PHPCR\String()
       */
      private $description;
  }
  

• Validation: Use Symfony validators on @Taxons:

  $builder->add('taxons', CollectionType::class, [
      'entry_type' => TextType::class,
      'constraints' => [new Length(['max' => 50])],
  ]);
  

Gotchas and Tips

Pitfalls

1. Path Configuration:

   • Taxonomy paths must exist in PHPCR before use. Create them manually or via a Command:

     $dm->createDocument('/var/www/data/tags')->save();
     

   • Hardcoding paths in annotations is not supported; always use the config.

2. Referrer Counts:

   • Counts are not automatic; run fix-referrer-counts after bulk operations or migrations.
   • Counts are stored as a separate property (referrerCount), not aggregated via PHPCR.

3. Case Sensitivity:

   • Taxon names are case-sensitive by default. Normalize case if needed:

     $taxonName = strtolower($taxonName);
     

4. Circular References:

   • Avoid bidirectional associations between documents and taxons that could cause infinite loops in serialization.

Debugging

• Missing Taxons: Check if the taxonomy path exists and is writable. Enable PHPCR logging:

  doctrine_phpcr:
      odm:
          logging: true
  

• Stale Counts: Clear counts and re-run fix-referrer-counts if counts appear incorrect.

Extension Points

1. Custom Taxon Storage: Override TaxonManager to use a different storage strategy (e.g., MongoDB for counts).

2. Hierarchical Tags (Planned): Implement a workaround with compound keys (e.g., "Laptops > Lenovo > X200" as a single string) until hierarchical support lands.

3. Static Taxonomies: Validate @Taxons against a predefined list:

   use Symfony\Component\Validator\Constraints as Assert;
   
   /**
    * @Assert\Choice(callback="getAllowedTaxons")
    */
   private $taxons;
   

Performance

• Batch Operations: Use TaxonManager::bulkCreateTaxons() for large-scale tag initialization:

  $taxonManager->bulkCreateTaxons(['tag1', 'tag2'], '/var/www/data/tags');
  

• Query Optimization: Cache TaxonObjects queries if used frequently:

  $taxon = $dm->getRepository(Taxon::class)->findOneBy(['name' => 'laravel']);