Doctrine Orm Bridge Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require bengor-user/doctrine-orm-bridge
   

   Ensure your project meets the requirement (PHP >= 5.5).

2. Configure Doctrine ORM Add the bridge to your Doctrine configuration (config/packages/doctrine.yaml):

   doctrine:
       orm:
           entity_managers:
               default:
                   mappings:
                       BenGorUser:
                           type: attribute
                           dir: "%kernel.project_dir%/vendor/bengor-user/user/src/Entity"
                           prefix: "BenGorUser\Entity"
                           alias: BenGorUser
   

3. First Use Case: User Entity Integration Extend the BenGorUser\Entity\User class in your own entity:

   namespace App\Entity;
   
   use BenGorUser\Entity\User as BaseUser;
   
   class User extends BaseUser
   {
       // Add custom fields or overrides here
   }
   

   Register the entity in your Doctrine configuration (as shown above).

Implementation Patterns

Workflow: Integrating User with Doctrine ORM

1. Extend the Base User Entity Create a custom user entity extending BenGorUser\Entity\User:

   namespace App\Entity;
   
   use BenGorUser\Entity\User;
   use Doctrine\ORM\Mapping as ORM;
   
   #[ORM\Entity(repositoryClass: "App\Repository\UserRepository")]
   class User extends User
   {
       #[ORM\Column(type: "string", length: 255, nullable: true)]
       private ?string $customField = null;
   
       // Getters/setters for custom fields
   }
   

2. Repository Integration Use the default repository or extend it:

   namespace App\Repository;
   
   use BenGorUser\Entity\User;
   use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
   use Doctrine\Persistence\ManagerRegistry;
   
   class UserRepository extends ServiceEntityRepository
   {
       public function __construct(ManagerRegistry $registry)
       {
           parent::__construct($registry, User::class);
       }
   
       // Custom query methods (e.g., findByRole)
   }
   

3. Leverage Doctrine Features Use Doctrine’s lifecycle callbacks, associations, and DQL:

   #[ORM\PrePersist]
   public function setCreatedAt(): void
   {
       $this->createdAt = new \DateTime();
   }
   
   #[ORM\ManyToMany(targetEntity: "App\Entity\Role")]
   private Collection $roles;
   

4. Authentication Integration Use Symfony’s security component with the Doctrine user provider:

   # config/packages/security.yaml
   security:
       providers:
           app_user_provider:
               entity:
                   class: App\Entity\User
                   property: email
   

Integration Tips

• Symfony Forms: Use the UserType from BenGorUser for form integration:

  use BenGorUser\Form\UserType;
  
  $builder->add('user', UserType::class);
  

• Validation: Extend the base validation constraints or add custom ones:

  use Symfony\Component\Validator\Constraints as Assert;
  
  #[Assert\NotBlank]
  #[Assert\Email]
  private ?string $email = null;
  

• Events: Listen to Doctrine lifecycle events for user-related logic:

  // src/EventListener/UserListener.php
  public function postPersist(User $user, LifecycleEventArgs $event)
  {
      $user->setLastLogin(new \DateTime());
  }
  

Gotchas and Tips

Pitfalls

1. Outdated Package

   • Last release was in 2017. Ensure compatibility with your Doctrine/Symfony versions.
   • Test thoroughly, especially if using newer Doctrine features (e.g., attributes over XML/YAML).

2. Namespace Conflicts

   • The package uses BenGorUser namespace. Avoid naming collisions in your project:

     // Bad: Overlapping namespace
     namespace BenGorUser\Entity; // Conflict!
     

   • Prefer App\Entity\User extending BenGorUser\Entity\User.

3. Missing Documentation

   • The README refers to external docs. Cross-reference with:
     • BenGorUser/User docs.
     • Doctrine’s entity mapping guide.

4. No Built-in Migrations

   • The package doesn’t include migrations. Create your own for schema changes:

     php bin/console make:migration
     

Debugging Tips

1. Entity Not Found Errors

   • Verify the mappings configuration in doctrine.yaml points to the correct directory:

     dir: "%kernel.project_dir%/vendor/bengor-user/user/src/Entity"
     

   • Check for typos in the prefix and alias.

2. Property Not Mapped

   • Ensure custom fields use Doctrine annotations/attributes:

     #[ORM\Column(type: "string")]
     private $customField;
     

   • Run php bin/console doctrine:schema:validate to check mappings.

3. Authentication Issues

   • Confirm the UserInterface is implemented (check BenGorUser\Entity\User).
   • Verify the security provider’s property (e.g., email) matches the user entity’s field.

Extension Points

1. Custom User Fields Extend the base entity and add fields:

   #[ORM\Column(type: "json")]
   private array $metadata = [];
   

2. Override Methods Override methods like getRoles() or getPassword():

   public function getRoles(): array
   {
       $roles = $this->roles->toArray();
       return empty($roles) ? ['ROLE_USER'] : $roles;
   }
   

3. Add Soft Deletes Use a library like stof/doctrine-extensions for soft deletes:

   #[ORM\Column(type: "boolean")]
   #[SoftDeleteable]
   private $deleted = false;
   

4. Event Subscribers Listen to user events (e.g., preUpdate):

   #[AsEventListener(event: "preUpdate", method: "onPreUpdate")]
   public function onPreUpdate(User $user, LifecycleEventArgs $event)
   {
       $user->setUpdatedAt(new \DateTime());
   }
   

Performance Considerations

• Eager-Load Associations Use fetch="EAGER" for frequently accessed associations:

  #[ORM\ManyToMany(targetEntity: "App\Entity\Role", fetch: "EAGER")]
  private Collection $roles;
  

• Query Optimization Add indexes to frequently queried fields (e.g., email):

  #[ORM\Column(type: "string", unique: true)]
  #[ORM\Index(columns: ["email"])]
  private ?string $email;