Doctrine Extensions Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sonata-project/doctrine-extensions
   

   Add to config/app.php under providers:

   Sonata\DoctrineExtensions\Provider\DoctrineExtensionsProvider::class,
   

2. Enable Extensions: Register the extensions in config/doctrine-extensions.php (auto-generated after installation):

   return [
       'orm' => [
           'timestampable' => true,
           'sluggable' => true,
           'tree' => true,
           // ...other extensions
       ],
   ];
   

3. First Use Case: Add Timestampable to an entity to auto-track createdAt/updatedAt:

   use Gedmo\Mapping\Annotation as Gedmo;
   
   /**
    * @Gedmo\Timestampable(on="create")
    */
   private $createdAt;
   
   /**
    * @Gedmo\Timestampable(on="update")
    */
   private $updatedAt;
   

Implementation Patterns

Common Workflows

1. Slug Generation:

   use Gedmo\Mapping\Annotation as Gedmo;
   
   /**
    * @Gedmo\Slug(fields={"title"}, unique=true)
    */
   private $slug;
   

   • Call updateSlug() manually if title changes outside form submission.

2. Tree Structures:

   use Gedmo\Mapping\Annotation as Gedmo;
   
   /**
    * @Gedmo\Tree(type="nested")
    */
   private $parent;
   

   • Use TreeManager to reorder nodes:

     $treeManager = $entityManager->getRepository('Gedmo\Tree\Entity\Repository\NestedTreeRepository');
     $treeManager->moveNode($node, $newParent);
     

3. Soft Deletes:

   use Gedmo\Mapping\Annotation as Gedmo;
   
   /**
    * @Gedmo\SoftDeleteable(fieldName="deletedAt")
    */
   private $deletedAt;
   

   • Query soft-deleted records with:

     $queryBuilder->andWhere('e.deletedAt IS NULL');
     

Integration Tips

• Doctrine Lifecycle Events: Use prePersist/preUpdate to trigger custom logic alongside extensions (e.g., validate slug uniqueness before save).

  public function prePersist(LifecycleEventArgs $args) {
      $entity = $args->getEntity();
      if ($entity instanceof SluggableInterface) {
          $entity->setSlug($entity->generateSlug());
      }
  }
  

• Custom Fields: Extend AbstractTimestampableEntity or AbstractTreeEntity for reusable base classes.

• QueryBuilder Shortcuts: Use TreeRepository methods like getChildren() or getSubtree() for nested queries.

Gotchas and Tips

Pitfalls

1. Annotation vs. YAML/XML:

   • Mixing annotation formats may cause conflicts. Stick to one per project.

2. Slug Uniqueness:

   • unique=true in @Slug requires a unique constraint in the DB. Add it via migration:

     $table->unique(['slug']);
     

3. Tree Performance:

   • Nested trees (type="nested") are slower for deep hierarchies. Use materialized_path for read-heavy apps.

4. Soft Deletes + Queries:

   • Forgetting to exclude soft-deleted records in queries returns stale data. Always filter with:

     $qb->andWhere('e.deletedAt IS NULL');
     

5. Timestampable Overrides:

   • Custom setCreatedAt()/setUpdatedAt() methods can break auto-updates. Avoid overriding unless necessary.

Debugging

• Enable SQL Logging:

  $entityManager->getConnection()->getConfiguration()->setSQLLogger(new \Doctrine\DBAL\Logging\EchoSQLLogger());
  

  Helps verify extension-generated queries (e.g., slug uniqueness checks).

• Check Event Subscribers: Extensions rely on Doctrine events. Verify they’re registered in config/packages/doctrine.yaml:

  doctrine:
      orm:
          event_subscribers:
              - Gedmo\Timestampable\TimestampableListener
              - Gedmo\Slugable\SlugableListener
  

Extension Points

1. Custom Slug Strategies: Override Gedmo\Slugable\SluggableListener to add logic (e.g., language-aware slugs).

2. Tree Types: Implement Gedmo\Tree\Type\TreeTypeInterface for custom tree storage (e.g., closure table).

3. Timestampable Fields: Extend Gedmo\Timestampable\TimestampableEntity to add createdBy/updatedBy fields:

   /**
    * @ORM\ManyToOne(targetEntity="User")
    * @Gedmo\Timestampable(on="create")
    */
   private $createdBy;
   

4. Event Hooks: Listen for onFlush to modify entities before save:

   $eventManager->addEventSubscriber(new class {
       public function onFlush(OnFlushEventArgs $args) {
           foreach ($args->getEntityChanges() as $entity) {
               if ($entity instanceof SluggableInterface) {
                   $entity->updateSlug();
               }
           }
       }
   });
   

5. Repository Shortcuts: Extend TreeRepository to add custom methods (e.g., getSiblings()).