Doctrine Extensions Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation Add the package via Composer:

   composer require axstrad/doctrine-extensions
   

   Register the service provider in config/app.php under providers:

   Axstrad\DoctrineExtensions\DoctrineExtensionsServiceProvider::class,
   

2. Basic Setup Ensure Doctrine ORM is properly configured in config/database.php (Laravel's default setup usually suffices). The package extends Doctrine's behavior, so no additional config is needed unless using specific extensions.

3. First Use Case: Soft Deletes Implement soft deletes in an Eloquent model:

   use Axstrad\DoctrineExtensions\SoftDeleteable\SoftDeleteableTrait;
   
   class User extends Model
   {
       use SoftDeleteableTrait;
   
       protected $dates = ['deleted_at'];
   }
   

   Now, User::destroy() will set deleted_at instead of deleting records.

Implementation Patterns

Common Workflows

1. Soft Deletes

   • Querying: Use withTrashed() to include soft-deleted records:

     User::withTrashed()->get();
     

   • Force Deletion: Use forceDelete() to permanently remove records:

     $user->forceDelete();
     

2. Sluggable Fields

   • Define a getSlug() method in your model:

     class Post extends Model
     {
         public function getSlug()
         {
             return Str::slug($this->title);
         }
     }
     

   • Use the sluggable behavior in queries or migrations.

3. Tree Structures (Nested Sets)

   • For hierarchical data (e.g., categories), use NestedSetTrait:

     class Category extends Model
     {
         use NestedSetTrait;
     
         protected $parentColumn = 'parent_id';
     }
     

   • Methods like getChildren(), getAncestors(), and moveUp() are available.

4. Timestamps

   • Extend created_at/updated_at with custom logic (e.g., auto-updating on specific fields):

     use Axstrad\DoctrineExtensions\Timestampable\TimestampableTrait;
     
     class Product extends Model
     {
         use TimestampableTrait;
     
         protected $timestampable = ['updated_at'];
     }
     

Integration Tips

• Migrations: Use SoftDeleteable in migrations to add deleted_at columns:

  Schema::table('users', function (Blueprint $table) {
      $table->softDeletes();
  });
  

• APIs: Leverage soft deletes to implement "archiving" logic without breaking relationships.
• Admin Panels: Use withTrashed() in admin panels to show deleted records for recovery.

Gotchas and Tips

Pitfalls

1. Doctrine vs. Eloquent Conflicts

   • The package extends Doctrine ORM, but Laravel uses Eloquent. Some behaviors (e.g., SoftDeleteable) may require manual trait application in Eloquent models.
   • Fix: Ensure traits are applied to Eloquent models explicitly (as shown above).

2. Missing Configuration

   • Some extensions (e.g., Sluggable) require additional setup in Doctrine configurations. Check the docs for extension-specific requirements.
   • Tip: Use php artisan vendor:publish to publish config files if available.

3. Performance with Large Trees

   • NestedSetTrait can slow queries on deep hierarchies. Use MaterializedPathTrait for better performance in large trees.
   • Tip: Index lft/rgt columns in migrations:

     $table->integer('lft')->index();
     $table->integer('rgt')->index();
     

4. Soft Deletes and Relationships

   • Soft-deleted models may break eager-loaded relationships if not handled carefully.
   • Tip: Use withTrashed() on both sides of relationships:

     User::with(['posts' => function ($query) {
         $query->withTrashed();
     }])->withTrashed()->get();
     

Debugging

• Query Logs: Enable Doctrine query logging in config/database.php:

  'logging' => true,
  

  Check logs for malformed queries (e.g., missing deleted_at in WHERE clauses).

• Trait Conflicts: If traits behave unexpectedly, verify:

  • No duplicate trait usage.
  • Parent classes aren’t overriding methods (e.g., boot() in Laravel models).

Extension Points

1. Custom Slug Logic Override getSlug() or use a callback:

   use Axstrad\DoctrineExtensions\Sluggable\SluggableTrait;
   
   class Post extends Model
   {
       use SluggableTrait;
   
       public function getSlugOptions()
       {
           return ['source' => 'custom_title'];
       }
   }
   

2. Soft Delete Events Listen for deleting and deleted events to add custom logic:

   User::deleting(function ($user) {
       // Pre-delete logic
   });
   
   User::deleted(function ($user) {
       // Post-delete logic (e.g., log deletion)
   });
   

3. Timestampable Extensions Extend TimestampableTrait to add custom timestamp fields:

   protected $timestampable = [
       'created_at',
       'updated_at',
       'archived_at' => 'archive', // Custom field
   ];