Upgrade Guide

This guide explains how to upgrade the Doctrine Encrypt Bundle between versions. For a list of changes in each version, see CHANGELOG.md.

General upgrade process

Back up configuration
Back up config/packages/nowo_doctrine_encrypt.yaml (or wherever you configure the bundle) before upgrading.
Check the changelog
Review CHANGELOG.md for the target version to see new features, changes, and breaking changes.

Update the package
Run:

composer update nowo-tech/doctrine-encrypt-bundle

Apply configuration and code changes
If the new version introduces or changes config options or namespaces, update your config and PHP code (see version-specific sections below).
Clear cache
```
php bin/console cache:clear
```
Test
Verify that encrypted entities are still read/written correctly and that console commands work.

Upgrading to 2.2.3

No breaking changes. Patch release (Spec Kit maintainer tooling, Twig |decrypt auto-escape fix, MysqlAes PHPDoc deprecation, composer.lock sync).

If your Twig templates relied on the |decrypt filter not being escaped (previous incorrect isSafe: ['html'] marking), apply |raw only when the decrypted content is trusted HTML:

{# Before (implicit unescaped output — incorrect) #}
{{ value|decrypt }}

{# After — default: escaped (recommended) #}
{{ value|decrypt }}

{# Only if decrypted HTML is trusted #}
{{ value|decrypt|raw }}

Update as usual:

composer update nowo-tech/doctrine-encrypt-bundle
php bin/console cache:clear

Upgrading to 2.2.2

No breaking changes. Patch release only (functional test / CI fix for PHP 8.4 + Symfony 8). No changes required in your application.

composer update nowo-tech/doctrine-encrypt-bundle

Upgrading to 2.2.1

No breaking changes. Patch release only (composer.lock sync + CI matrix fix). Recommended if you installed 2.2.0 and hit CI/composer validate issues, or want the Symfony 8.0 / 8.1 CI fix from upstream.

composer update nowo-tech/doctrine-encrypt-bundle

Or pin explicitly:

composer require nowo-tech/doctrine-encrypt-bundle:^2.2.1

Upgrading to 2.2.0

Breaking changes for legacy environments:

PHP 8.2+ is now required (require.php was >=8.1). Upgrade PHP before updating the bundle.
Symfony 6.x is no longer declared in composer.json (symfony/* are ^7.0 || ^8.0 only). If you still run Symfony 6 or PHP 8.1, pin the previous line:
```
composer require nowo-tech/doctrine-encrypt-bundle:">=2.0,<2.2"
```
Or upgrade the application to PHP 8.2+ and Symfony 7.4+ or 8.x, then:
```
composer require nowo-tech/doctrine-encrypt-bundle:^2.2
```

No configuration or encryptor changes are required when you already run PHP 8.2+ and Symfony 7.4+ / 8.x.

Upgrading to 2.1.0

No breaking changes for existing applications using Halite or Defuse.

Optional: MySQL AES interoperability

To use the new MysqlAes encryptor (compatible with MySQL AES_ENCRYPT / AES_DECRYPT):

# config/packages/nowo_doctrine_encrypt.yaml
nowo_doctrine_encrypt:
    configs:
        mysql_aes:
            encryptor_class: MysqlAes
            secret_key_env_var: '%env(MYSQL_AES_KEY)%'

Generate a passphrase:

php bin/console doctrine:encrypt:generate-secret-key mysql_aes

Use on entity properties: #[Encrypted('mysql_aes')]. For native SQL on BLOB columns (no <ENC> marker), see MYSQL_AES.md.

Requires PHP ext-openssl (typically enabled). Prefer Halite/Defuse for new application-level encryption unless you must interoperate with MySQL functions.

Update as usual:

composer update nowo-tech/doctrine-encrypt-bundle
php bin/console cache:clear

Upgrading to 2.0.10

No breaking changes. This release fixes the Symfony 7.1+ deprecation (Extension class) and corrects COMMANDS.md (batchSize default). No changes required in your application.

Update as usual:

composer update nowo-tech/doctrine-encrypt-bundle
php bin/console cache:clear

Upgrading to 2.0.9

No breaking changes. This release applies code style (PHP-CS-Fixer), internal refactors, and demo/CI updates; no changes required in your application.

Update as usual:

composer update nowo-tech/doctrine-encrypt-bundle
php bin/console cache:clear

Upgrading to 2.0.8

No breaking changes. This release fixes unit tests for Symfony Console 7.0/8.0 compatibility (RotateKeysCommandTest); no changes required in your application.

Update as usual:

composer update nowo-tech/doctrine-encrypt-bundle
php bin/console cache:clear

Upgrading to 2.0.7

No breaking changes. New features:

doctrine:encrypt:status now lists each encrypted property and its config per entity, and shows configured encryptor configs at the end.
doctrine:encrypt:rotate-keys runs the full key rotation (optional backup, decrypt, change keys, re-encrypt) with step-by-step confirmation; use --backup and/or --no-interaction as needed.
doctrine:encrypt:generate-secret-key accepts --force to overwrite existing key files without asking.
doctrine:decrypt:database and doctrine:encrypt:database accept --force to skip the confirmation prompt.
Config: Optional nowo_doctrine_encrypt.batch_size (default 5) for encrypt/decrypt database batch size. FrankenPHP is supported (see INSTALLATION.md); no config changes needed.

Update as usual:

composer update nowo-tech/doctrine-encrypt-bundle
php bin/console cache:clear