Doctrine Extensions Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require ebidtech/doctrine-extensions-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Ebidtech\DoctrineExtensionsBundle\EbidtechDoctrineExtensionsBundle::class => ['all' => true],
   ];
   

2. Enable Extensions Configure Doctrine extensions in config/packages/doctrine.yaml:

   doctrine:
       orm:
           mappings:
               gedmo_loggable: ~
               gedmo_timestampable: ~
               gedmo_translatable: ~
               # Add other extensions as needed (e.g., `gedmo_tree`, `gedmo_sortable`)
   

3. First Use Case: Timestampable Entities Apply the Timestampable trait to an entity (e.g., Post):

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

   Run migrations (php bin/console doctrine:migrations:diff + php bin/console doctrine:migrations:migrate).

Implementation Patterns

Common Workflows

1. Logging Entity Changes Use Loggable to track modifications:

   use Gedmo\Mapping\Annotation as Gedmo;
   
   class Product
   {
       /**
        * @Gedmo\Loggable
        */
       private $name;
   }
   

   • Configure logging in config/packages/doctrine_extensions.yaml:

     ebidtech_doctrine_extensions:
         loggable: true
     

2. Translatable Entities For multilingual support:

   use Gedmo\Mapping\Annotation as Gedmo;
   
   class Article
   {
       /**
        * @Gedmo\TranslationEntity(class="App\Entity\ArticleTranslation")
        */
       private $title;
   }
   

   • Create a translation entity (e.g., ArticleTranslation) with locale and field fields.

3. Tree Structures Use Tree for hierarchical data (e.g., categories):

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

   • Run php bin/console doctrine:query:sql "SELECT * FROM category_tree".

4. Sortable Lists For ordered lists (e.g., menus):

   use Gedmo\Mapping\Annotation as Gedmo;
   
   class MenuItem
   {
       /**
        * @Gedmo\SortablePosition
        */
       private $position;
   }
   

Integration Tips

• Doctrine Lifecycle Events: Extensions often hook into prePersist, preUpdate, etc. Override these if custom logic is needed.
• Custom Fields: Extend existing traits (e.g., Timestampable) by adding your own logic in postLoad/preFlush events.
• QueryBuilder: Use DQL functions like GEDMO_SLUG or GEDMO_TRANSLATE in repositories:

  $query->addSelect('GEDMO_TRANSLATE(e.title, :locale) as translatedTitle');
  

Gotchas and Tips

Pitfalls

1. Outdated Package

   • Last release in 2015; verify compatibility with your Laravel/Symfony version (targets Symfony 2.x).
   • Workaround: Fork the repo and update dependencies (e.g., doctrine/doctrine-extensions) manually.

2. Missing Configuration

   • Extensions like Loggable require a log_entry table. Run migrations after enabling:

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

3. Circular References in Trees

   • Tree extension throws errors if parent-child cycles exist. Validate with:

     $category->getParent()->getRoot(); // Check for cycles
     

4. Translation Locale Handling

   • Translatable fields require a locale column in the translation table. Ensure it’s set in ArticleTranslation:

     /**
      * @ORM\Column(type="string", length=20)
      */
     private $locale;
     

5. Performance with Loggable

   • Logging every field change can bloat the database. Use @Gedmo\Loggable(skipOnNull=true) to optimize.

Debugging

• Enable SQL Logging: Add to config/packages/dev/doctrine.yaml:

  doctrine:
      dbal:
          logging: true
          profiling: true
  

• Check Event Listeners: Verify extensions are registered via:

  php bin/console debug:event-dispatcher
  

  Look for gedmo.* listeners.

Extension Points

1. Custom Log Entry Class Override the default LogEntry by configuring in doctrine_extensions.yaml:

   ebidtech_doctrine_extensions:
       loggable:
           log_entry_class: App\Entity\CustomLogEntry
   

2. Slug Generation Customize slugs by implementing Gedmo\Sluggable\SluggableListener:

   $slugger->setTransliteration(true);
   $slugger->setSeparator('-');
   

3. Tree Type Switch between nested, materialized_path, or closure_table in annotations:

   @Gedmo\Tree(type="materialized_path")
   

4. Timestamp Format Override default timestamps by adding a setter:

   public function setCreatedAt(\DateTimeInterface $date): self
   {
       $this->createdAt = $date->format('Y-m-d H:i:s.u');
       return $this;
   }