Doctrine Entities Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require dbstudios/doctrine-entities
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Dbstudios\DoctrineEntities\DoctrineEntitiesServiceProvider"
   

2. Basic Usage Register a Doctrine entity in config/doctrine-entities.php:

   'entities' => [
       'App\Models\User' => [
           'entity' => 'User',
           'namespace' => 'App\\Entities',
       ],
   ],
   

   Generate the entity class (if not auto-generated):

   php artisan doctrine-entities:generate
   

3. First Use Case Use the generated entity in a repository or service:

   use App\Entities\User;
   
   $user = new User();
   $user->name = 'John Doe';
   $user->save(); // Uses Doctrine ORM under the hood
   

Implementation Patterns

Workflow Integration

1. Model-Entity Mapping

   • Keep Eloquent models for database interactions but use Doctrine entities for complex business logic.
   • Example:

     // Eloquent model (API/database layer)
     class User extends Model {}
     
     // Doctrine entity (business logic layer)
     class User extends \Dbstudios\DoctrineEntities\Entity {}
     

2. Repository Pattern

   • Create a custom repository to bridge Eloquent and Doctrine:

     namespace App\Repositories;
     
     use App\Entities\User;
     use Dbstudios\DoctrineEntities\Repository;
     
     class UserRepository extends Repository
     {
         public function findByName($name)
         {
             return $this->findOneBy(['name' => $name]);
         }
     }
     

3. Service Layer Abstraction

   • Use entities in services to decouple business logic from ORM:

     namespace App\Services;
     
     use App\Entities\User;
     use App\Repositories\UserRepository;
     
     class UserService
     {
         protected $repository;
     
         public function __construct(UserRepository $repository)
         {
             $this->repository = $repository;
         }
     
         public function createUser(array $data)
         {
             $user = new User();
             $user->fromArray($data); // Hydrate entity
             $this->repository->save($user);
             return $user;
         }
     }
     

4. Event Listeners

   • Attach Doctrine lifecycle callbacks to entities:

     namespace App\Entities;
     
     use Doctrine\Common\Annotations\PrePersist;
     
     class User extends \Dbstudios\DoctrineEntities\Entity
     {
         /**
          * @PrePersist
          */
         public function setCreatedAt()
         {
             $this->created_at = now();
         }
     }
     

Gotchas and Tips

Pitfalls

1. Outdated Doctrine Version

   • The package was last updated in 2017 and may not support modern Laravel/Doctrine versions.
   • Workaround: Manually patch or fork the package for compatibility.

2. Entity Generation Overwrites

   • Running doctrine-entities:generate will overwrite existing entity files.
   • Tip: Use doctrine-entities:generate --force sparingly; prefer manual edits for critical logic.

3. No Built-in Migration Support

   • The package does not generate migrations for new entities.
   • Tip: Use Laravel migrations alongside Doctrine entities for schema changes.

4. Circular Dependencies

   • If entities reference each other (e.g., User has Post and Post has User), ensure proper lazy-loading:

     // In User.php
     public function getPosts()
     {
         return $this->hasMany(Post::class);
     }
     

Debugging Tips

1. Enable Doctrine Logging Add to config/doctrine-entities.php:

   'logging' => true,
   

   Logs will appear in storage/logs/doctrine.log.

2. Check Entity Metadata Dump metadata to debug mappings:

   use Doctrine\ORM\Mapping\ClassMetadata;
   
   $metadata = $this->entityManager->getClassMetadata(User::class);
   dump($metadata->getFieldNames());
   

3. Transaction Handling Wrap operations in transactions to avoid partial saves:

   $entityManager->beginTransaction();
   try {
       $user->save();
       $entityManager->commit();
   } catch (\Exception $e) {
       $entityManager->rollBack();
       throw $e;
   }
   

Extension Points

1. Custom Hydration Override fromArray() in entities to handle custom data mapping:

   public function fromArray(array $data)
   {
       $this->name = $data['full_name'] ?? $data['name'];
       $this->email = $data['email_address'];
   }
   

2. Event Subscribers Attach Doctrine events globally in AppServiceProvider:

   public function boot()
   {
       $this->app->make('doctrine')->getEventManager()->addEventSubscriber(
           new \App\Doctrine\EventSubscribers\AuditSubscriber()
       );
   }
   

3. Custom Entity Manager Bind a custom Doctrine EntityManager in AppServiceProvider:

   $this->app->singleton('doctrine', function () {
       $config = $this->app['config']['doctrine-entities'];
       return \Doctrine\ORM\EntityManager::create($config['connection'], $config['metadata']);
   });