Doctrine Encrypted Contracts Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The package provides abstractions for Doctrine ORM encrypted column types, which aligns with use cases requiring sensitive data encryption at the database layer (e.g., PII, financial data, or compliance-driven fields).
• Laravel Compatibility: Since Laravel uses Doctrine ORM via Eloquent (or standalone Doctrine in some cases), this package could integrate with:
  • Eloquent models (via Doctrine DBAL under the hood).
  • Custom Doctrine-based repositories (e.g., in hybrid Laravel/Symfony apps).
• Abstraction Layer: Designed as a foundation for building encrypted column extensions, meaning it’s not a standalone solution but a building block for a larger encryption strategy (e.g., pairing with aeliot/doctrine-encrypted-bundle).
• Potential Gaps:
  • No native Laravel service provider or Eloquent integration (would require custom glue code).
  • Limited adoption (0 stars, dependents) suggests unproven stability in production.

Integration Feasibility

• Doctrine ORM Dependency: Requires Doctrine DBAL (Laravel includes this via doctrine/dbal), but not Doctrine ORM itself (which Laravel typically avoids).
  • Feasible for projects already using Doctrine ORM (e.g., Symfony/Laravel hybrids).
  • Challenge: Eloquent users would need to bridge Doctrine DBAL types to Eloquent casts/accessors.
• Encryption Backend: Assumes an external encryption library (e.g., defuse/php-encryption, openssl). Compatibility depends on the chosen library.
• Database Support: Works with any DBAL-supported database (MySQL, PostgreSQL, SQLite, etc.), but encryption performance varies by DB (e.g., PostgreSQL’s pgcrypto vs. application-side encryption).

Technical Risk

• High Customization Burden:
  • No out-of-the-box Laravel/Eloquent integration → manual mapping of encrypted columns to model attributes.
  • Example: Requires defining custom Doctrine Types and Eloquent casts to handle encrypted fields.
• Performance Overhead:
  • Encryption/decryption happens per-query (unless using DB-native encryption like PostgreSQL’s pgcrypto).
  • Risk of N+1 query issues if not optimized (e.g., lazy-loading encrypted fields).
• Security Risks:
  • Key management is not handled by this package (must integrate with a KMS or custom solution).
  • Plaintext exposure: If decryption fails (e.g., wrong key), the app may crash or leak errors.
• Maturity Risks:
  • No active maintenance signals (last release Dec 2024, but no stars/dependents).
  • Undocumented edge cases (e.g., transactions, bulk operations).

Key Questions

1. Use Case Validation:
   • Is field-level encryption (vs. TLS/DB encryption) a strict requirement?
   • Are you using Doctrine ORM or just Eloquent? If the latter, how will you bridge the gap?
2. Encryption Strategy:
   • What encryption library will you pair this with? Does it support the required algorithms (AES-256-GCM, etc.)?
   • How will encryption keys be managed (KMS, environment variables, etc.)?
3. Performance:
   • What’s the expected query volume for encrypted fields? Can the DB handle the overhead?
   • Will you use DB-native encryption (e.g., PostgreSQL pgcrypto) to reduce app-side load?
4. Alternatives:
   • Have you evaluated Laravel-native solutions like:
     • vlucas/phpdotenv + openssl (manual encryption).
     • spatie/laravel-encryption (simpler, but less flexible).
     • Database-level encryption (e.g., PostgreSQL TDE, AWS KMS).
5. Long-Term Viability:
   • Given the package’s lack of adoption, are you comfortable with potential breaking changes or abandonware risk?
   • Is there a maintainer or community you can engage with for support?

Integration Approach

Stack Fit

Migration Path

1. Assess Current Encryption:
   • Audit existing sensitive fields (e.g., password, credit_card).
   • Determine if field-level encryption is needed vs. TLS/DB encryption.
2. Set Up Dependencies:
   • Install the package:

     composer require aeliot/doctrine-encrypted-contracts
     

   • Add a Doctrine-compatible encryption library (e.g., defuse/php-encryption).
3. Define Custom Doctrine Types:
   • Extend Aeliot\DoctrineEncryptedContracts\Type\EncryptedType for your use case.
   • Example:

     use Aeliot\DoctrineEncryptedContracts\Type\EncryptedType;
     
     class CreditCardType extends EncryptedType {
         protected function getEncryptionKey(): string { return config('encryption.credit_card_key'); }
     }
     

4. Integrate with Eloquent (if needed):
   • Create an Eloquent accessor/mutator to handle encrypted fields:

     public function getCreditCardAttribute($value) {
         return $this->decrypt($value);
     }
     

   • Or use a cast:

     protected $casts = [
         'credit_card' => EncryptedCast::class,
     ];
     

5. Database Schema Update:
   • Modify migrations to use the new Doctrine type (if using Doctrine ORM).
   • For Eloquent, ensure the column type matches (e.g., TEXT for encrypted strings).

Compatibility

• Doctrine DBAL: ✅ Fully compatible (Laravel includes this).
• Eloquent: ⚠️ Requires manual bridging (no built-in support).
• Laravel Services: ❌ No native integration with:
  • Request validation (e.g., Illuminate\Validation).
  • API resources (e.g., Illuminate\Http\Resources).
  • Scouting (e.g., Laravel Scout).
• Caching: ⚠️ Encrypted data may bypass cache (e.g., Redis) if not handled carefully.

Sequencing

1. Phase 1: Proof of Concept
   • Implement one encrypted field (e.g., credit_card) in a non-critical module.
   • Test with manual key management (e.g., environment variables).
2. Phase 2: Full Integration
   • Roll out to all sensitive fields.
   • Integrate with key management system (KMS) (e.g., AWS KMS, HashiCorp Vault).
3. Phase 3: Optimization
   • Benchmark query performance with encrypted fields.
   • Consider DB-native encryption (e.g., PostgreSQL pgcrypto) to reduce app-side load.
4. Phase 4: Monitoring
   • Log decryption failures (e.g., wrong keys).
   • Monitor query latency for encrypted fields.

Operational Impact

Maintenance

• Custom Code Overhead:
  • High: Requires custom Doctrine types, Eloquent casts, and encryption key management.
  • Example: If the package evolves, your abstraction layer may need updates.
• Dependency Risks:
  • Doctrine DBAL: Stable, but Laravel’s Eloquent team may deprioritize DBAL features.
  • Encryption Library: If you switch libraries (e.g., from defuse to openssl), you’ll need to rewrite type handlers.
• Key Rotation:
  • Manual process unless integrated with a KMS (e.g., AWS KMS, HashiCorp Vault).
  • Downtime risk if keys are rotated without proper fallback.

Support

• Community: ❌ Nonexistent (0 stars, no issues, no maintainer engagement).
  • Workarounds: You’ll need to reverse-engineer the package’s intended usage.
• Debugging:
  • Poor error messages: Encryption failures may not surface clearly in Laravel’s exception handler.