Extradoctrine Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require appventus/extradoctrine-bundle
   

   Register the bundle in config/bundles.php (Symfony 4+):

   return [
       // ...
       AppVentus\DoctrineBundle\ExtraDoctrineBundle::class => ['all' => true],
   ];
   

2. Enable DQL Functions Add the custom DQL function to your Doctrine configuration (config/packages/doctrine.yaml):

   doctrine:
       orm:
           dql:
               string_functions:
                   lpad: AppVentus\DoctrineBundle\ORM\Query\AST\Functions\LpadFunction
   

3. First Use Case Use LPAD in a query builder to pad strings with zeros (e.g., formatting dates):

   $qb = $entityManager->createQueryBuilder();
   $qb->select('b')
      ->from('App\Entity\Bill', 'b')
      ->where($qb->expr()->eq(
          $qb->expr()->concat('b.year', 'LPAD(b.month, 2, \'0\')'),
          '202305' // Expected: "202305" (May 2023)
      ));
   

Implementation Patterns

Query Builder Workflows

1. String Padding Use LPAD to standardize string lengths (e.g., month/day formatting):

   $qb->expr()->concat(
       'entity.field',
       'LPAD(entity.incrementalId, 5, \'0\')'
   );
   

2. Dynamic Padding Pass dynamic values (e.g., from user input) via literals:

   $padLength = $qb->expr()->literal($request->request->get('pad_length'));
   $qb->where($qb->expr()->like(
       'LPAD(entity.code, ' . $padLength . ', \'0\')',
       '00123%'
   ));
   

3. Reusable DQL Functions Extend the bundle to add more functions (e.g., RPAD, TRIM) by:

   • Creating new AST\Functions\* classes.
   • Registering them in doctrine.yaml under string_functions.

Integration Tips

• Symfony Forms: Use LPAD in form queries to validate padded inputs (e.g., ZIP codes).
• API Responses: Pad numeric IDs in serializers for consistency:

  // In a custom serializer normalizer
  $paddedId = 'LPAD(' . $entity->getId() . ', 8, \'0\')';
  

Gotchas and Tips

Pitfalls

1. Case Sensitivity The function name in DQL must match exactly (LPAD, not lpad or lPad). Errors like:

   [SyntaxError] line 0, col 10: Error: Class 'AppVentus\DoctrineBundle\ORM\Query\AST\Functions\lpadFunction' not found
   

   occur if the case differs.

2. Doctrine Version Mismatch The bundle targets Symfony 2.3+ and Doctrine ORM 2.x. Test thoroughly with newer versions (e.g., Symfony 5+).

3. Query Caching Padded expressions may break query cache if not handled as literals. Use expr()->literal() for dynamic values:

   // Bad: Direct interpolation (may cause cache issues)
   $qb->where('LPAD(field, ' . $var . ', \'0\') = ?1');
   
   // Good: Use literals
   $length = $qb->expr()->literal($var);
   $qb->where('LPAD(field, ' . $length . ', \'0\') = ?1');
   

Debugging

• Enable SQL Logging Add to config/packages/dev/doctrine.yaml:

  doctrine:
      dbal:
          logging: true
          profiling: true
  

  Check generated SQL for malformed LPAD calls.

• AST Function Paths Verify the namespace in doctrine.yaml matches the bundle’s autoloaded class:

  composer dump-autoload
  

Extension Points

1. Add New Functions Follow the LpadFunction pattern to create custom DQL functions:

   namespace App\Doctrine\AST\Functions;
   
   use Doctrine\ORM\Query\AST\Functions\FunctionNode;
   use Doctrine\ORM\Query\Lexer;
   use Doctrine\ORM\Query\Parser;
   
   class RpadFunction extends FunctionNode {
       private $field;
       private $length;
       private $padChar;
   
       public function parse(Parser $parser) {
           $parser->match(Lexer::T_IDENTIFIER);
           $this->field = $parser->StringPrimary();
           $this->length = $parser->ArithmeticPrimary();
           $this->padChar = $parser->StringPrimary();
       }
   
       public function getSql(\Doctrine\ORM\Query\SqlWalker $sqlWalker) {
           return 'RPAD(' . $this->field->dispatch($sqlWalker) . ', ' .
                  $this->length->dispatch($sqlWalker) . ', ' .
                  $this->padChar->dispatch($sqlWalker) . ')';
       }
   }
   

   Register in doctrine.yaml:

   doctrine:
       orm:
           dql:
               string_functions:
                   rpad: App\Doctrine\AST\Functions\RpadFunction
   

2. Override Existing Behavior Extend the bundle’s classes (e.g., LpadFunction) in a custom bundle to modify logic (e.g., add validation).