Download the PHP package nowo-tech/doctrine-encrypt-bundle without Composer

Doctrine Encrypt Bundle

⭐ Found this useful? Install from Packagist · Give it a star on GitHub so more developers can find it.

Symfony bundle to encrypt Doctrine entity fields at rest using Halite or Defuse—audited libraries, no custom crypto. For Symfony 7.4+ and 8 · PHP 8.2+. Suits GDPR and compliance (e.g. Art. 32); supports key rotation and AnonymizeBundle for anonymization and erasure.

This bundle is FrankenPHP worker mode friendly (including when the kernel is not reset between requests; see docs/FRANKENPHP-WORKER-AUDIT.md).

Table of contents

• Quick search terms
• Features
• Installation
• Requirements
• Configuration
• Usage
• Demo
• Development
• Documentation
• Tests and coverage
• License
• Author

Quick search terms

Looking for Doctrine encryption, encrypt entity fields, Halite Symfony, Defuse encryption, field-level encryption, encrypt database column, Symfony encrypt attribute, Doctrine Encrypted? You're in the right place.

Features

• ✅ Encrypt and decrypt entity properties with a single attribute
• ✅ Multiple encryptor profiles — e.g. personal_data (Halite) and financial_data (Defuse) in the same app, each with its own key
• ✅ Halite, Defuse, and MysqlAes (MySQL AES_ENCRYPT / AES_DECRYPT compatible) — audited or interoperable crypto; see MYSQL_AES.md
• ✅ Transparent: encrypt on persist/update, decrypt on load
• ✅ EncryptUtil — programmatic encrypt() / decrypt() with optional config name (default or e.g. financial_data)
• ✅ MaskUtil — mask sensitive values in PHP (e.g. show only last N chars); usable in services. MaskUtil::secretHint() / |secret_hint show that a secret is saved without revealing it (•••• 1234)
• ✅ "Leave blank to keep" secret fields — SecretFieldApplier::apply() (clear → null, new value → set, blank → keep) and an optional SecretType form field (never pre-filled, •••• 1234 hint, optional clear checkbox; needs symfony/form). See Usage
• ✅ Key file hardening — key directories created 0770, key files kept at 0600; checked on every console command and at most once per minute per worker on HTTP (FrankenPHP worker-safe). See Configuration → secret_permissions
• ✅ Twig filters — |decrypt (decrypt in templates; optional config: {{ value|decrypt }} or {{ value|decrypt('financial_data') }}) and |mask (mask for display: {{ value|mask(4) }} or {{ value|decrypt|mask(4) }})
• ✅ Works with embedded entities and inheritance
• ✅ Console commands: status, generate secret key, encrypt/decrypt database, rotate keys (backup, decrypt, change keys, re-encrypt with confirmations)
• ✅ Key rotation — one command or manual steps; combinable with AnonymizeBundle for GDPR-compliant anonymization and erasure
• ✅ Symfony Flex recipe stub — see docs/INSTALLATION.md (recipes-contrib merge is still pending; Flex applies it when the recipe is enabled)
• ✅ Compatible with Symfony 7.4+ and 8 and Doctrine ORM 2.x and 3.x
• ✅ Compatible with FrankenPHP (HTTP runtime and optional worker mode; demos default to APP_ENV=dev with Caddyfile.dev, i.e. no PHP worker — see Installation → FrankenPHP)

Installation

With Symfony Flex, the recipe (when enabled) registers the bundle and creates the config file automatically. Without Flex, see docs/INSTALLATION.md for manual steps.

Manual registration in config/bundles.php:

Requirements

• PHP >= 8.2
• Symfony 7.4+ or 8 (^7.4 || ^8.0; tested on 7.4, 8.0, 8.1). See composer.json.
• Doctrine ORM ^3.7 and DoctrineBundle ^2.13 || ^3.0
• Twig ^3.2 (filters are registered via getFilters(), no #[AsTwigFilter] / TwigBundle 7.3 requirement)
• paragonie/halite (included); for Defuse: defuse/php-encryption ^2.1
• ext-sodium recommended for Halite (or sodium_compat)

See docs/UPGRADING.md for compatibility notes.

Configuration

Create config/packages/nowo_doctrine_encrypt.yaml. You can use one encryptor (legacy) or multiple named profiles (recommended).

Multiple profiles (recommended)

Use different encryptors and keys per kind of data (e.g. personal vs financial):

Defuse: composer require defuse/php-encryption ^2.1

Key files: one per profile, e.g. .Halite.personal_data.key, .Defuse.financial_data.key in the profile’s secret_directory_path. Add to .gitignore:

Generate keys: php bin/console doctrine:encrypt:generate-secret-key (creates missing Halite/Defuse keys for all profiles, or pass a profile alias). See docs/COMMANDS.md.

Single encryptor (one profile)

Use one entry under profiles (e.g. default):

Key file: .Halite.default.key (or .Defuse.default.key). Full options: docs/CONFIGURATION.md.

Usage

Mark entity properties with the Encrypted attribute. Use no argument (or "default") for the default config, or the config name when using multiple profiles:

With multiple profiles, pass the config alias per property:

Values are encrypted on persist/update and decrypted on load. For programmatic use: EncryptUtil (encrypt/decrypt) and MaskUtil (mask for display). In Twig use the |decrypt and |mask filters. See docs/USAGE.md for EncryptUtil, MaskUtil, Twig filters, embedded entities, and inheritance.

Demo

The Symfony 8 demo is in demo/symfony8. It runs with FrankenPHP and Caddy (HTTP on port 80 in the container). FRANKENPHP_MODE selects classic or worker (default worker in .env.example) — docs/DEMO.md.

Development

Run tests and QA with Docker: make up && make install && make test (or make test-coverage, make qa). Without Docker: composer install && composer test. See Makefile for all targets.

Documentation

• Installation
• Configuration
• PSR evaluation (REQ-CS-007)
• Usage
• Contributing
• Code of Conduct
• Changelog
• Upgrading
• Release
• Security
• Engram
• Spec-driven development
• GitHub Spec Kit
• Roadmap

Additional documentation

• GitHub Actions CI requirements
• Demo with FrankenPHP (development and production)
• FrankenPHP worker audit (kernel not reset)
• Example
• Commands
• Key rotation
• Demo
• Custom encryptor
• MySQL AES_ENCRYPT / AES_DECRYPT (MysqlAes)
• Performance (encryptors, LIKE, scalability)
• Coverage policy
• PHPStan level and baseline

Tests and coverage

• Tests: PHPUnit (unit and functional suites)
• PHP: 100.00% of includable src/ (see docs/COVERAGE.md for justified exclusions)
• Run: make test-coverage

License

The MIT License (MIT). Please see LICENSE for more information.

Author

Created by Héctor Franco Aceituno at Nowo.tech