Doctrine Encrypt Bundle Laravel Package

Getting Started

Minimal Setup

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

   composer require aware/doctrine-encrypt-bundle
   

   Register the bundle in config/bundles.php (Symfony) or config/app.php (Laravel via Symfony integration):

   return [
       // ...
       Aware\DoctrineEncryptBundle\AwareDoctrineEncryptBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="Aware\DoctrineEncryptBundle\AwareDoctrineEncryptBundle" --tag="config"
   

   Update config/doctrine_encrypt.php with your encryption key (e.g., from .env):

   return [
       'encryption_key' => env('ENCRYPTION_KEY', 'your-32-byte-key-here'),
       'algorithm' => 'AES-256-CBC', // Default; adjust if needed
   ];
   

3. First Use Case: Encrypting a Field Annotate a Doctrine entity property with @Encrypt:

   use Aware\DoctrineEncryptBundle\Annotation\Encrypt;
   
   /**
    * @ORM\Entity
    */
   class User {
       /**
        * @ORM\Column(type="string")
        * @Encrypt()
        */
       private $ssn;
   }
   

   Run migrations (php artisan doctrine:migrations:diff → php artisan doctrine:migrations:migrate).

Implementation Patterns

Workflow: Secure Sensitive Data

1. Define Encrypted Fields Use @Encrypt on Doctrine entity properties (e.g., credit_card, password_hash).

   /**
    * @Encrypt(algorithm="AES-128-CBC", key="custom-key")
    */
   private $apiToken;
   

2. Querying Encrypted Data The bundle handles decryption transparently. Queries work as usual:

   $user = $entityManager->getRepository(User::class)->findOneBy(['ssn' => 'encrypted-value']);
   // Decrypted automatically when fetched.
   

3. Bulk Operations Use DQL or QueryBuilder—encryption/decryption is managed under the hood:

   $qb = $entityManager->createQueryBuilder();
   $qb->select('u')
      ->from(User::class, 'u')
      ->where('u.ssn = :ssn')
      ->setParameter('ssn', 'plaintext-value');
   

4. Custom Encryption Logic Extend the bundle’s EncryptableListener to add pre/post-encryption logic:

   use Aware\DoctrineEncryptBundle\Event\EncryptEvent;
   
   $eventDispatcher->addListener(
       EncryptEvent::PRE_ENCRYPT,
       function (EncryptEvent $event) {
           $event->setData(strtoupper($event->getData()));
       }
   );
   

Gotchas and Tips

Pitfalls

1. Key Management

   • Never hardcode keys in config. Use environment variables or a secure vault.
   • Key rotation: The bundle doesn’t support dynamic key changes. Plan migrations carefully.

2. Performance Overhead

   • Encryption adds latency. Avoid encrypting frequently queried fields (e.g., id).
   • Test with large datasets to benchmark impact.

3. Doctrine Events

   • Overriding PRE_ENCRYPT/POST_DECRYPT events may break serialization if data types change.

4. Database Indexes

   • Encrypted fields cannot be indexed in most databases. Use partial indexes or application-side filtering.

Debugging

• Enable Logging Add to config/doctrine_encrypt.php:

  'debug' => env('APP_DEBUG', false),
  

  Logs encryption/decryption events to var/log/doctrine_encrypt.log.

• Verify Encryption Check raw DB values vs. decrypted PHP values:

  $user = $entityManager->find(User::class, 1);
  var_dump($user->getSsn()); // Decrypted
  var_dump($entityManager->getConnection()->fetchAssociative('SELECT ssn FROM user WHERE id = 1')); // Encrypted
  

Extension Points

1. Custom Algorithms Implement Aware\DoctrineEncryptBundle\Encryptor\EncryptorInterface:

   class CustomEncryptor implements EncryptorInterface {
       public function encrypt($data, string $algorithm, string $key): string {
           // Custom logic
       }
       public function decrypt(string $data, string $algorithm, string $key): string {
           // Custom logic
       }
   }
   

   Register in config/doctrine_encrypt.php:

   'encryptors' => [
       'custom' => CustomEncryptor::class,
   ],
   

2. Field-Level Overrides Use @Encrypt attributes to override defaults per field:

   /**
    * @Encrypt(algorithm="AES-128-CBC", key="field-specific-key")
    */
   private $secretData;
   

3. Excluding Fields Add @ORM\Column(encryptable=false) to opt out:

   /**
    * @ORM\Column(type="string", encryptable=false)
    */
   private $nonSecureField;