Stof Doctrine Extensions Bundle Laravel Package

Getting Started

Minimal Steps

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

   composer require aciliainternet/stof-doctrine-extensions-bundle
   

   Enable the bundle in config/bundles.php:

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

2. Database Configuration Ensure your config/packages/doctrine.yaml includes the extensions:

   doctrine:
       orm:
           mappings:
               gedmo_loggable:
                   type: attribute
                   prefix: Gedmo\Loggable\Entity
                   dir: "%kernel.project_dir%/vendor/gedmo/doctrine-extensions/src/Loggable/Entity"
                   alias: GedmoLoggable
               # Add other extensions (e.g., timestampable, translatable) similarly
   

3. First Use Case: Soft-Deletes Enable soft-deletes in your entity:

   use Gedmo\Mapping\Annotation as Gedmo;
   use Doctrine\ORM\Mapping as ORM;
   
   #[ORM\Entity]
   #[Gedmo\SoftDeleteable(fieldName: 'deletedAt')]
   class Product
   {
       #[ORM\Column(type: 'datetime', nullable: true)]
       private ?\DateTimeInterface $deletedAt = null;
   }
   

   Run migrations and test soft-deletion:

   $product = $entityManager->find(Product::class, 1);
   $entityManager->remove($product); // Soft-deletes instead of hard-delete
   

Implementation Patterns

Common Workflows

1. Logging Entity Changes Use Gedmo\Loggable to track changes:

   #[Gedmo\Loggable]
   class User
   {
       // ...
   }
   

   Configure logging in config/packages/stof_doctrine_extensions.yaml:

   stof_doctrine_extensions:
       loggable: true
       orm:
           default:
               log_entry_class: App\Entity\LogEntry
   

2. Sluggable URLs Generate SEO-friendly slugs:

   #[Gedmo\Sluggable]
   class Article
   {
       #[ORM\Column(length: 255)]
       #[Gedmo\Slug(fields: ['title'])]
       private string $slug;
   }
   

3. Timestampable Entities Auto-manage createdAt/updatedAt:

   #[Gedmo\Timestampable(on: 'create')]
   #[ORM\Entity]
   class Comment
   {
       #[ORM\Column(type: 'datetime')]
       private \DateTimeInterface $createdAt;
   }
   

Integration Tips

• Doctrine Lifecycle Callbacks: Combine with native Doctrine events (e.g., prePersist) for custom logic.
• QueryBuilder Extensions: Use Gedmo\SoftDeleteable\Query\TreeWalker\SoftDeleteableTreeWalker for soft-delete queries.
• Symfony Forms: Bind slug fields dynamically in form types:

  $builder->add('slug', TextType::class, [
      'disabled' => true, // Let Gedmo generate it
  ]);
  

Gotchas and Tips

Pitfalls

1. Outdated Package

   • Last release in 2015—verify compatibility with your Doctrine/Symfony version (e.g., test with doctrine/orm:^2.10).
   • Fork or patch if critical bugs arise (e.g., PHP 8.x support).

2. Configuration Overrides

   • Extensions may conflict with native Doctrine features (e.g., createdAt vs. Gedmo\Timestampable). Explicitly disable one if needed:

     stof_doctrine_extensions:
         timestampable: false
     

3. Slug Collisions

   • Sluggable fields may generate duplicates. Use a custom sluggable listener or add a unique constraint:

     #[ORM\Column(length: 255, unique: true)]
     #[Gedmo\Slug(fields: ['title'], unique: ['slug'])]
     

Debugging

• Enable SQL Logging: Check if extensions are firing queries:

  doctrine:
      dbal:
          logging: true
          profiling: true
  

• Event Subscribers: Verify listeners are registered (e.g., Gedmo\Loggable\LoggableListener).

Extension Points

1. Custom Log Entry Class Extend Gedmo\Loggable\Entity\LogEntry for additional fields:

   class AppLogEntry extends AbstractLogEntry
   {
       #[ORM\Column(type: 'string', length: 255)]
       private string $userIp;
   }
   

2. Dynamic Field Mapping Use Gedmo\Mapping\Driver\AnnotationDriver for runtime field resolution (e.g., multi-language slugs).

3. Hybrid Soft-Deletes Combine with isDeleted flag for complex logic:

   #[Gedmo\SoftDeleteable(fieldName: 'deletedAt')]
   class Product
   {
       #[ORM\Column(type: 'boolean')]
       private bool $isDeleted = false;
   
       // Custom logic in preRemove()
   }