Doctrine Extensions Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require antishov/doctrine-extensions-bundle
   

   Enable the bundle in config/bundles.php:

   Stof\DoctrineExtensionsBundle\StofDoctrineExtensionsBundle::class => ['all' => true],
   

2. First Use Case: Use the Timestampable behavior to auto-track createdAt and updatedAt fields in an entity:

   use Gedmo\Mapping\Annotation as Gedmo;
   
   #[ORM\Entity]
   class Post
   {
       #[ORM\Column(type: 'datetime')]
       #[Gedmo\Timestampable(on: 'create')]
       private $createdAt;
   
       #[ORM\Column(type: 'datetime')]
       #[Gedmo\Timestampable(on: 'update')]
       private $updatedAt;
   }
   

   Run php bin/console doctrine:schema:update --force to apply changes.

Key Dependencies

• gedmo/doctrine-extensions (v2.3.4+ or v3.0+): Core behaviors (e.g., Slugable, Loggable).
• Symfony 4.4+ or 5.0+: Compatible with PHP 7.2.5+ or 8.0+.

Implementation Patterns

Common Workflows

1. Entity Behaviors:

   • Slugable: Auto-generate SEO-friendly URLs.

     #[Gedmo\Slug(fields: ['title'])]
     private $slug;
     

   • Loggable: Track changes to entities.

     #[Gedmo\Loggable]
     class Product { ... }
     

   • Uploadable: Handle file uploads with validation.

     #[Gedmo\Uploadable(filePath: 'uploads/products')]
     private $imagePath;
     

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

   #[Gedmo\Tree(type: 'nested')]
   class Category { ... }
   

3. Soft Deletes:

   #[Gedmo\SoftDeleteable(fieldName: 'deletedAt')]
   class User { ... }
   

   Query soft-deleted records:

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

4. Translatable:

   #[Gedmo\Translatable]
   class Article { ... }
   

   Requires gedmo/doctrine-extensions:translatable and a translation manager.

Integration Tips

• Doctrine Events: Listen to prePersist/preUpdate for custom logic:

  #[ORM\PrePersist]
  public function setDefaultValues(): void {
      $this->createdAt = new \DateTime();
  }
  

• Custom Repositories: Extend Doctrine\ORM\EntityRepository for behavior-specific queries.
• Validation: Use Symfony’s Assert constraints with Uploadable:

  #[Assert\File(maxSize: '1024k')]
  private $file;
  

Gotchas and Tips

Pitfalls

1. Uploadable Paths:

   • Windows Paths: Use forward slashes (/), not backslashes (\), to avoid crashes.
   • Directory Permissions: Ensure the upload directory exists and is writable:

     mkdir -p uploads/products && chmod -R 775 uploads
     

2. Soft Deletes + Loggable:

   • Loggable events may not trigger for soft-deleted entities. Explicitly exclude them:

     #[Gedmo\Loggable(logEntryClass: 'App\Entity\LogEntry')]
     #[Gedmo\SoftDeleteable(fieldName: 'deletedAt')]
     class Post { ... }
     

3. Slug Conflicts:

   • Resolve duplicate slugs by appending a suffix (e.g., -2):

     #[Gedmo\Slug(options: ['unique' => true, 'separator' => '-'])]
     private $slug;
     

4. NestedSet Performance:

   • Avoid deep hierarchies (>5 levels) to prevent query timeouts. Use materializedPath for large trees.

Debugging

• Doctrine Events: Enable debug logging for gedmo events:

  # config/packages/dev/doctrine.yaml
  doctrine:
      orm:
          eventmanager: 'doctrine.eventmanager'
  

  Log events in a custom subscriber:

  public function onPrePersist(LifecycleEventArgs $args): void {
      \Log::debug('PrePersist: ' . $args->getObject()->getClassName());
  }
  

• Uploadable Errors:

  • Check UploadableManager for validation failures:

    $manager = $this->container->get('stof_doctrine_extensions.uploadable.manager');
    $manager->validate($entity);
    

Extension Points

1. Custom Behaviors: Extend Gedmo\Mapping\Driver\AnnotationDriver to add annotations:

   #[Gedmo\CustomBehavior('app_custom_behavior')]
   class Entity { ... }
   

2. Event Subscribers: Override default behavior (e.g., modify Loggable entries):

   #[AsEventSubscriber]
   class CustomLogSubscriber implements EventSubscriber {
       public function getSubscribedEvents(): array {
           return [LifecycleEvents::prePersist];
       }
       public function prePersist(LifecycleEventArgs $args): void { ... }
   }
   

3. Configuration: Override default settings in config/packages/stof_doctrine_extensions.yaml:

   stof_doctrine_extensions:
       uploadable:
           default_upload_dir: '%kernel.project_dir%/public/uploads'
           allowed_mime_types: ['image/jpeg', 'image/png']