Doctrine Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer (recommended):

   composer require doctrine/doctrine-bundle:^2.1
   

   Ensure your composer.json includes Symfony 2.3+ and Doctrine DBAL/ORM dependencies.

2. Enable the Bundle: Add to app/AppKernel.php:

   new Doctrine\Bundle\DoctrineBundle\DoctrineBundle(),
   

3. Configure Database: Edit app/config/config.yml:

   doctrine:
       dbal:
           driver:   "%database_driver%"
           host:     "%database_host%"
           dbname:   "%database_name%"
           user:     "%database_user%"
           password: "%database_password%"
           charset:  UTF8
       orm:
           auto_generate_proxy_classes: "%kernel.debug%"
           auto_mapping: true
   

4. First Use Case: Create an entity (e.g., src/AppBundle/Entity/User.php):

   namespace AppBundle\Entity;
   use Doctrine\ORM\Mapping as ORM;
   
   /** @ORM\Entity */
   class User {
       /** @ORM\Id @ORM\Column(type="integer") @ORM\GeneratedValue */
       private $id;
       /** @ORM\Column(type="string") */
       private $name;
   }
   

   Run migrations:

   php app/console doctrine:schema:update --force
   

Implementation Patterns

Core Workflows

1. Entity Management:

   • Use annotations (@ORM\*) or YAML/XML for mappings.
   • Generate entities from existing DB:

     php app/console doctrine:mapping:import AppBundle annotation
     

2. Repository Pattern: Extend Doctrine\ORM\EntityRepository for custom queries:

   namespace AppBundle\Entity;
   use Doctrine\ORM\EntityRepository;
   
   class UserRepository extends EntityRepository {
       public function findByName($name) {
           return $this->createQueryBuilder('u')
               ->where('u.name = :name')
               ->setParameter('name', $name)
               ->getQuery()
               ->getResult();
       }
   }
   

3. DQL Queries: Fetch data via EntityManager:

   $users = $entityManager->createQuery('SELECT u FROM AppBundle:User u WHERE u.name = :name')
       ->setParameter('name', 'John')
       ->getResult();
   

4. Lifecycle Callbacks: Hook into entity events (e.g., @ORM\PrePersist):

   /** @ORM\PrePersist */
   public function setCreatedAt() {
       $this->createdAt = new \DateTime();
   }
   

Integration Tips

• Symfony Forms: Bind entities to forms:

  $form = $this->createFormBuilder($user)
      ->add('name')
      ->getForm();
  

• Validation: Use Symfony’s validator with Doctrine constraints:

  /** @ORM\Column(type="string", length=50) @Assert\NotBlank */
  private $name;
  

• Events: Listen to Doctrine events (e.g., onFlush):

  $eventManager->addEventListener(
      \Doctrine\ORM\Events::onFlush,
      function ($eventArgs) { /* ... */ }
  );
  

Gotchas and Tips

Pitfalls

1. Proxy Classes:

   • Clear cache after adding new entities:

     php app/console cache:clear
     

   • Debug proxy issues with:

     php app/console doctrine:query:sql "SELECT u FROM AppBundle:User u"
     

2. Circular References:

   • Use @ORM\Backpack or @ORM\Transient to break cycles.

3. MySQL Joins:

   • This fork supports cross-database joins, but test thoroughly in MySQL 5.7+.

4. Transaction Isolation:

   • Avoid long-running transactions; use setIsolationLevel() if needed.

Debugging

• Query Logging: Enable in config.yml:

  doctrine:
      dbal:
          logging: true
  

  Logs appear in app/logs/doctrine.dbal.

• Schema Validation:

  php app/console doctrine:schema:validate
  

Extension Points

1. Custom Types: Register via Doctrine\DBAL\Types\Type:

   $type = new CustomType();
   $doctrine->getConnection()->getDatabasePlatform()->registerDoctrineTypeMapping('custom', $type);
   

2. Event Subscribers: Implement Doctrine\Common\EventSubscriber for ORM events.

3. Custom DQL Functions: Register via Doctrine\ORM\Query\AST\Functions\FunctionNode:

   $queryBuilder->addCustomDqlFunction('custom_func', 'AppBundle\Query\CustomFunc');
   

Configuration Quirks

• Auto-Mapping: Ensure auto_mapping: true and mappings are configured for non-annotation setups.
• Connection Names: Use default or define multiple connections in dbal.connections.