Doctrine Extensions Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require stof/doctrine-extensions-bundle
   

   Enable in config/bundles.php:

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

2. Configure Doctrine Extensions Add to config/packages/doctrine.yaml:

   stof_doctrine_extensions:
       orm:
           default:
               timestampable: true
               tree: true
               sluggable: true
               # ... other extensions
   

3. First Use Case: Timestampable Entities Annotate an entity with @ORM\HasLifecycleCallbacks and use Timestampable:

   use Gedmo\Mapping\Annotation as Gedmo;
   
   /**
    * @Gedmo\Timestampable(on="create")
    */
   class Post
   {
       // ...
   }
   

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

Implementation Patterns

Common Workflows

1. Tree Structures (Nested Set)

   • Use @Gedmo\Tree for hierarchical data (e.g., categories).
   • Example:

     /**
      * @Gedmo\Tree(type="nested")
      */
     class Category
     {
         // ...
     }
     

   • Query with getChildren() or getParent().

2. Slug Generation

   • Auto-generate slugs with @Gedmo\Slug.
   • Customize via sluggable config:

     stof_doctrine_extensions:
         orm:
             default:
                 sluggable:
                     fields: ["title"]
                     separator: "-"
     

3. Soft Deletes

   • Enable with @Gedmo\SoftDeleteable.
   • Query soft-deleted records with ->where('deletedAt IS NULL').

4. Loggable Changes

   • Track field changes with @Gedmo\Loggable.
   • Configure in config/packages/doctrine.yaml:

     stof_doctrine_extensions:
         orm:
             default:
                 loggable: true
     

Integration Tips

• Event Listeners: Extend behavior with custom listeners (e.g., pre-slug generation).
• Custom Extensions: Create reusable extensions by extending AbstractExtension.
• Doctrine Events: Hook into prePersist, preUpdate for validation (e.g., slug uniqueness).

Gotchas and Tips

Pitfalls

1. Missing Migrations

   • Always run doctrine:migrations:diff after adding new extensions (e.g., tree, sluggable).
   • Example: ALTER TABLE posts ADD COLUMN lft INT.

2. Circular References in Trees

   • Avoid infinite loops in nested sets by validating parent-child relationships manually.

3. Slug Conflicts

   • Default slug generation may collide. Use unique config:

     sluggable:
         unique: true
     

4. Performance with Loggable

   • Loggable can bloat your database. Use sparingly or archive old logs.

Debugging

• Enable SQL Logging

  doctrine:
      dbal:
          logging: true
  

  Check for unexpected queries (e.g., UPDATE on soft deletes).

• Check Event Order Use debug:event-dispatcher to verify extension listeners fire correctly.

Extension Points

1. Custom Slug Strategies Override Stoke\DoctrineExtensions\Sluggable\SluggableListener for dynamic slugs.

2. Tree Traversal Extend Gedmo\Tree\TreeListener for custom path queries (e.g., depth-limited trees).

3. Timestampable Formatting Format timestamps via setDateTimeFormat() in the listener.

4. Soft Delete Queries Override getQuery() in SoftDeleteableListener to exclude soft-deleted records by default.

Config Quirks

• Disable Extensions Per Entity Use orm: { default: { ... }, Your\Entity: { timestampable: false } }.
• Multi-Database Support Configure extensions per connection in stof_doctrine_extensions.orm.