Doctrine Cariboo Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cariboo/doctrine-cariboo
   

   Ensure doctrine/orm is installed (this package extends Doctrine ORM).

2. First Use Case: Basic Entity Extension Add the package’s Cariboo\Doctrine\Extensions\* traits to your Doctrine entities. Example:

   use Cariboo\Doctrine\Extensions\SoftDeletable\SoftDeletableTrait;
   
   #[ORM\Entity]
   class User
   {
       use SoftDeletableTrait;
   
       // ...
   }
   

   • Where to Look First:
     • src/Extensions for available traits.
     • config/doctrine-cariboo.php (if published) for global configurations.

Implementation Patterns

Common Workflows

1. Soft Deletes

   • Enable via SoftDeletableTrait and configure the deletedAt column.
   • Query soft-deleted records:

     $repository->findAll(['deletedAt' => null]); // Non-deleted
     $repository->findAll(['deletedAt' => null, 'withDeleted' => true]); // All (including soft-deleted)
     

   • Integration Tip: Override prePersist/preRemove in your entity to auto-set deletedAt.

2. Audit Logging

   • Use AuditLoggableTrait to track changes:

     use Cariboo\Doctrine\Extensions\AuditLoggable\AuditLoggableTrait;
     
     class Product
     {
         use AuditLoggableTrait;
         // ...
     }
     

   • Configure the audit log table in config/doctrine-cariboo.php:

     'audit_log' => [
         'table_name' => 'product_audit_logs',
     ],
     

3. Sluggable URLs

   • Apply SluggableTrait to generate slugs from a field (e.g., title):

     use Cariboo\Doctrine\Extensions\Sluggable\SluggableTrait;
     
     class BlogPost
     {
         use SluggableTrait;
     
         #[ORM\Column]
         private string $title;
     
         #[ORM\Column(length: 255, unique: true)]
         private string $slug;
     
         public function getSlugSource(): string
         {
             return $this->title;
         }
     }
     

   • Workflow: Call $entity->generateSlug() before saving.

4. Event Dispatching

   • Extend Doctrine events (e.g., postPersist) with EventDispatcherTrait:

     use Cariboo\Doctrine\Extensions\EventDispatcher\EventDispatcherTrait;
     
     class Order
     {
         use EventDispatcherTrait;
     
         protected function dispatchEvents(): void
         {
             $this->dispatch('order.created', $this);
         }
     }
     

Integration Tips

• Repository Layer: Create custom repository methods to leverage extensions (e.g., findActive() for soft deletes).
• Migrations: Update existing tables to include new columns (e.g., deletedAt, slug) via Laravel migrations.
• Testing: Mock traits in unit tests by extending base entities or using partial mocks.

Gotchas and Tips

Pitfalls

1. Missing Configuration

   • Extensions like AuditLoggable require a configured table. Forgetting to publish/config the package may cause silent failures.
   • Fix: Run php artisan vendor:publish --tag=doctrine-cariboo-config and update config/doctrine-cariboo.php.

2. Trait Conflicts

   • Overlapping lifecycle callbacks (e.g., prePersist in multiple traits) can cause issues.
   • Tip: Use parent::method() to chain trait logic or override explicitly.

3. Slug Uniqueness

   • SluggableTrait does not enforce uniqueness by default. Add a unique constraint to the slug column in your migration:

     $table->string('slug')->unique();
     

4. Soft Deletes and Queries

   • Forgetting withDeleted: true in queries will exclude soft-deleted records, even if the trait is applied.
   • Debugging Tip: Check if deletedAt is null in your query builder:

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

5. Event Dispatching Order

   • Events dispatched via EventDispatcherTrait run after Doctrine’s default events. Use EventDispatcher::DISPATCHER_PRIORITY_* constants to adjust priority.

Extension Points

1. Customizing Audit Logs

   • Override getAuditLogData() in your entity to include/exclude fields:

     protected function getAuditLogData(): array
     {
         return [
             'old_data' => $this->getChanges(),
             'custom_field' => $this->getCustomField(),
         ];
     }
     

2. Dynamic Slug Sources

   • Implement getSlugSource() dynamically (e.g., based on locale):

     public function getSlugSource(): string
     {
         return $this->title . '-' . app()->getLocale();
     }
     

3. Adding New Extensions

   • The package follows a modular trait-based design. To add a new extension:
     1. Create a trait in src/Extensions/.
     2. Register lifecycle callbacks (e.g., prePersist, postLoad).
     3. Document the trait’s requirements (e.g., column names).

Debugging Tips

• Enable Doctrine Logging:

  $entityManager->getConnection()->getConfiguration()->setSQLLogger(new \Doctrine\DBAL\Logging\EchoSQLLogger());
  

• Check Trait Methods: Use get_class_methods(\stdClass::class) to inspect loaded traits at runtime.
• Query Builder: Dump the query SQL to verify soft-deletes/audit logic:

  $qb->getQuery()->getSQL(); // Debug SQL