Doctrine Type Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require drjele/doctrine-type
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Drjele\DoctrineType\DoctrineTypeServiceProvider"
   

2. Basic Usage Register a custom Doctrine type in your Laravel app by extending the base type system:

   use Drjele\DoctrineType\DoctrineType;
   use Doctrine\DBAL\Types\Type;
   
   // Define a new type (e.g., for UUIDs, JSON, or custom formats)
   Type::addType('custom_type', DoctrineType::class);
   

3. First Use Case Use the type in a Laravel model via Doctrine DBAL (if integrating with Eloquent via a custom accessor/mutator or a hybrid ORM):

   use Doctrine\DBAL\Types\Type;
   
   // Example: Store a JSON string as a custom type
   $type = Type::getType('custom_type');
   $value = $type->convertToDatabaseValue(['key' => 'value'], $platform);
   

Implementation Patterns

Common Workflows

1. Custom Type Registration Extend DoctrineType to handle serialization/deserialization:

   class JsonType extends DoctrineType {
       public function convertToDatabaseValue($value, Platform $platform) {
           return json_encode($value);
       }
   
       public function convertToPHPValue($value, Platform $platform) {
           return json_decode($value, true);
       }
   }
   Type::addType('json', JsonType::class);
   

2. Integration with Eloquent Use a model accessor/mutator or a custom attribute cast to bridge Doctrine types with Eloquent:

   // In a model
   protected $casts = [
       'metadata' => 'array', // Cast to array (handled by Doctrine type)
   ];
   
   // Or via a custom attribute
   public function getMetadataAttribute($value) {
       $type = Type::getType('json');
       return $type->convertToPHPValue($value, $this->getConnection()->getDoctrineSchemaManager()->getDatabasePlatform());
   }
   

3. Query Builder Integration Use raw Doctrine queries via Laravel’s DB::connection()->getDoctrineConnection():

   $doctrineConnection = DB::connection()->getDoctrineConnection();
   $query = $doctrineConnection->createQueryBuilder()
       ->select('u')
       ->from('users', 'u')
       ->where('u.metadata->>\'$.key\' = :value')
       ->setParameter('value', 'target')
       ->getQuery();
   

Hybrid ORM Patterns

• Doctrine + Eloquent: Use Doctrine for complex queries and Eloquent for simplicity.
• Shared Models: Define models in Doctrine and hydrate them into Eloquent entities via a mapper.

Gotchas and Tips

Pitfalls

1. Platform-Specific Quirks

   • Doctrine types must handle platform differences (e.g., MySQL vs. PostgreSQL JSON support).
   • Test convertToDatabaseValue/convertToPHPValue across platforms.

2. Caching Issues

   • Doctrine types are cached; clear the cache after registration:

     php artisan doctrine:cache:clear
     

3. Eloquent Integration Gaps

   • Eloquent’s query builder doesn’t natively support Doctrine types. Use raw queries or custom accessors.

4. Type Registration Order

   • Register types before they’re used (e.g., in a service provider’s boot() method).

Debugging Tips

• Log Raw SQL: Use Doctrine’s logging to inspect generated queries:

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

• Check Platform Compatibility: Ensure your type works with all target databases.

Extension Points

1. Custom Platforms Override getSQLDeclaration for platform-specific schema definitions:

   public function getSQLDeclaration(array $column, Platform $platform) {
       return match ($platform->getName()) {
           'postgresql' => 'JSONB',
           default => 'TEXT',
       };
   }
   

2. Validation Add validation logic in convertToDatabaseValue:

   if (!is_array($value)) {
       throw new \InvalidArgumentException('Value must be an array.');
   }
   

3. Doctrine Events Listen to onFlush or postLoad for lifecycle hooks:

   $eventManager->addEventListener(
       \Doctrine\ORM\Events::postLoad,
       function ($event) {
           // Transform loaded data
       }
   );