PHPackages                             caeligo/field-encryption-bundle - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. caeligo/field-encryption-bundle

ActiveSymfony-bundle[Database & ORM](/categories/database)

caeligo/field-encryption-bundle
===============================

A Symfony bundle for transparent Doctrine entity field encryption using AES-256-CBC

v1.4.0(1mo ago)023MITPHPPHP >=8.2

Since Dec 26Pushed 1mo agoCompare

[ Source](https://github.com/biga156/field-encryption-bundle)[ Packagist](https://packagist.org/packages/caeligo/field-encryption-bundle)[ RSS](/packages/caeligo-field-encryption-bundle/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (18)Versions (6)Used By (0)

FieldEncryptionBundle
=====================

[](#fieldencryptionbundle)

A Symfony bundle for transparent Doctrine entity field encryption using AES-256-CBC for string fields and AES-256-GCM for binary files.

[![PHP](https://camo.githubusercontent.com/0f16581d1180dbfd4c0e13166ec1267d4ad2f2fab8281ea6d6b284cf5c65d921/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d626c75652e737667)](https://php.net)[![Symfony](https://camo.githubusercontent.com/c786cdaaca91e8091119a6ab20ef404c7fe26ba50aa7c47066c23494c98ce59d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f53796d666f6e792d362e34253230253743253230372e782d626c61636b2e737667)](https://symfony.com)[![License](https://camo.githubusercontent.com/784362b26e4b3546254f1893e778ba64616e362bd6ac791991d2c9e880a3a64e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e2e737667)](LICENSE)

Features
--------

[](#features)

- 🔐 **Automatic encryption/decryption** - Transparent for your application code
- 📝 **String field encryption** - AES-256-CBC with HMAC-SHA256 hash for searching
- 📁 **Binary file encryption** - AES-256-GCM for documents, images, etc.
- 🔑 **HKDF key derivation** - Cryptographic key separation for different purposes
- 🛡️ **Timing-safe comparison** - Protection against timing attacks on hash verification
- 🏷️ **Attribute-based configuration** - Simple `#[Encrypted]` and `#[EncryptedFile]` attributes
- 🔄 **Key rotation support** - Safely rotate keys with progress tracking
- 🗜️ **Optional compression** - Gzip compression for binary files
- 📋 **Metadata storage** - Store MIME type, filename, size alongside encrypted content
- 🛠️ **Console commands** - Key generation, rotation wizard, data migration

Requirements
------------

[](#requirements)

- PHP 8.2+
- Symfony 6.4+ or 7.x
- Doctrine ORM 2.14+ or 3.x

Installation
------------

[](#installation)

```
composer require caeligo/field-encryption-bundle
```

Register the bundle in `config/bundles.php`:

```
return [
    // ...
    Caeligo\FieldEncryptionBundle\FieldEncryptionBundle::class => ['all' => true],
];
```

Quick Start
-----------

[](#quick-start)

### 1. Generate Encryption Key

[](#1-generate-encryption-key)

```
php bin/console field-encryption:generate-key --append-to-env
```

### 2. Configure the Bundle

[](#2-configure-the-bundle)

```
# config/packages/field_encryption.yaml
field_encryption:
    encryption_key: '%env(FIELD_ENCRYPTION_KEY)%'
```

### 3. Add Attributes to Your Entity

[](#3-add-attributes-to-your-entity)

```
use Caeligo\FieldEncryptionBundle\Attribute\Encrypted;
use Caeligo\FieldEncryptionBundle\Attribute\EncryptedEntity;

#[ORM\Entity]
#[EncryptedEntity]
class User
{
    #[ORM\Column(type: Types::TEXT, nullable: true)]
    #[Encrypted(hashField: true, hashProperty: 'emailHash')]
    private ?string $email = null;

    #[ORM\Column(type: Types::TEXT, nullable: true, unique: true)]
    private ?string $emailHash = null;

    private ?string $plainEmail = null;  // Transient, auto-populated

    public function getEmail(): ?string
    {
        return $this->plainEmail;
    }

    public function setEmail(?string $email): self
    {
        $this->plainEmail = $email;
        return $this;
    }
}
```

**That's it!** The bundle automatically encrypts on save and decrypts on load.

Documentation
-------------

[](#documentation)

DocumentDescription[String Encryption](docs/string-encryption.md)Encrypting text fields (emails, names, etc.)[File Encryption](docs/file-encryption.md)Encrypting binary files (documents, images)[Console Commands](docs/commands.md)Key generation, rotation, migration commands[Key Rotation](docs/key-rotation.md)Safely rotating encryption keys[Configuration](docs/configuration.md)Complete configuration referenceBasic Examples
--------------

[](#basic-examples)

### Encrypted String Field

[](#encrypted-string-field)

```
#[Encrypted(hashField: true)]
private ?string $email = null;

private ?string $plainEmail = null;
private ?string $emailHash = null;
```

### Encrypted File Field

[](#encrypted-file-field)

```
use Caeligo\FieldEncryptionBundle\Attribute\EncryptedFile;
use Caeligo\FieldEncryptionBundle\Model\EncryptedFileData;

#[EncryptedFile(mimeTypeProperty: 'mimeType', originalNameProperty: 'fileName')]
private $document;

private ?EncryptedFileData $plainDocument = null;
private ?string $mimeType = null;
private ?string $fileName = null;
```

### Working with Files

[](#working-with-files)

```
// From upload
$fileData = EncryptedFileData::fromUploadedFile($uploadedFile);
$entity->setPlainDocument($fileData);

// To download
$content = $entity->getPlainDocument()->getContent();
$mimeType = $entity->getPlainDocument()->getMimeType();
```

Console Commands
----------------

[](#console-commands)

```
# Generate new encryption key
php bin/console field-encryption:generate-key

# Rotate encryption keys (interactive wizard)
php bin/console field-encryption:rotate-keys --wizard

# Encrypt existing unencrypted data
php bin/console field-encryption:encrypt-existing --dry-run
```

Security Considerations
-----------------------

[](#security-considerations)

- ⚠️ **Never commit encryption keys** - Use environment variables
- 💾 **Backup your keys** - Key loss = data loss
- 🔄 **Plan key rotation** - Use the wizard for safe rotation
- 🔍 **Use hashes for search** - Enable `hashField` for searchable fields
- 🆔 **Use ULID/UUID** - Don't use sequential integers for key derivation
- 🌶️ **Consider hash pepper** - Use `hash_pepper` config for extra key separation

### Database Compromise Protection

[](#database-compromise-protection)

This bundle provides strong protection if only your database is compromised:

Attacker seesCan read?NotesEncrypted fields❌ NoAES-256 encryptedHash fields⚠️ Hash onlyHMAC-SHA256, not reversiblePlain metadata✅ YesStore sensitive metadata separately**Key requirement**: The encryption key must NOT be stored in the database.

License
-------

[](#license)

MIT License - see [LICENSE](LICENSE)

Author
------

[](#author)

Bíró Gábor ([@biga156](https://github.com/biga156))

Repository
----------

[](#repository)

- **GitHub**:
- **Packagist**:

###  Health Score

41

—

FairBetter than 89% of packages

Maintenance88

Actively maintained with recent releases

Popularity9

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~21 days

Total

5

Last Release

58d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/6f1738e4aaa964821919352c90570f60dd0ea4517f2b7bcf00eec08264c7d58f?d=identicon)[biga156](/maintainers/biga156)

---

Top Contributors

[![biga156](https://avatars.githubusercontent.com/u/25263934?v=4)](https://github.com/biga156 "biga156 (9 commits)")

---

Tags

symfonybundlesecurityencryptionaesdoctrinegdpr

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/caeligo-field-encryption-bundle/health.svg)

```
[![Health](https://phpackages.com/badges/caeligo-field-encryption-bundle/health.svg)](https://phpackages.com/packages/caeligo-field-encryption-bundle)
```

###  Alternatives

[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.3M152](/packages/sulu-sulu)[sonata-project/doctrine-orm-admin-bundle

Integrate Doctrine ORM into the SonataAdminBundle

46117.7M155](/packages/sonata-project-doctrine-orm-admin-bundle)[rcsofttech/audit-trail-bundle

Enterprise-grade, high-performance Symfony audit trail bundle. Automatically track Doctrine entity changes with split-phase architecture, multiple transports (HTTP, Queue, Doctrine), and sensitive data masking.

1022.4k](/packages/rcsofttech-audit-trail-bundle)[ahmed-bhs/doctrine-doctor

Runtime analysis tool for Doctrine ORM integrated into Symfony Web Profiler. Unlike static linters, it analyzes actual query execution at runtime to detect performance bottlenecks, security vulnerabilities, and best practice violations during development with real execution context and data.

813.1k](/packages/ahmed-bhs-doctrine-doctor)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)