Symfony Doctrine Encrypt Laravel Package

Product Decisions This Supports

• Field-level encryption as a buy-vs-build call. This release makes the "buy" case materially stronger: the package now ships a runnable reference application (.example/) that exercises every public capability against real database engines — ORM read/write of encrypted fields, deterministic e-mail lookup, refusal to search randomised columns, lookups spanning active salt versions during a rotation, the encrypt/decrypt commands over a legacy plaintext table, and online salt rotation with checks before and after. That is exactly the evidence a build-vs-buy review needs, and it removes a costly discovery phase from our own integration work.
• A credible roadmap item for salted/envelope encryption rotation. Online salt rotation with batch checkpointing, a scope-bound checkpoint, and a documented --dry-run --verify check turns "rotate encryption keys" from a scary migration project into a scheduled operational task. If compliance or a customer security questionnaire has ever asked about key rotation cadence, this is the artefact that lets us commit to a cadence rather than answer "annually, under change control, with downtime."
• Retrofit path for legacy plaintext tables. Encrypt/decrypt commands over an existing plaintext table mean we can bring an old schema under field-level encryption without a big-bang rewrite — a decision that often blocks a compliance commitment on acquired or long-lived datasets.
• Searchable encryption with an honest boundary. Deterministic lookup by e-mail (and the explicit refusal to search a randomised column) gives product a clear design constraint: encrypted fields support exact-match lookups, not range or full-text. That informs feature scoping for search, admin filtering, and reporting before engineering writes code, not after.
• Operational safety as a shippable claim. The v4.7.0 correctness fixes are directly product-relevant: an interrupted database:rotate can no longer be resumed by database:encrypt or against a stale salt; a second run in the same process no longer skips every row and reports success; a short write of the checkpoint file no longer overwrites the last good checkpoint. Those were silent-data-loss and false-success classes of bug in the runbook we would otherwise have to build defensive tooling around.
• Quality signal for vendor-risk review. Mutation-score thresholds raised from 81 to 95 (both minMsi and minCoveredMsi), plus an example CI job against two database services. Useful in a vendor due-diligence or architecture-review write-up.
• Use cases this unlocks: PII and health-data fields at rest, deterministic identifier lookups (e-mail, customer reference), multi-tenant or multi-scope encryption with separate salts, and salt rotation as a recurring maintenance job rather than a project.

When to Consider This Package

Consider it when:

• We are on PHP with Doctrine ORM (Laravel via a Doctrine bridge, or Symfony). This is a Doctrine DBAL/ORM-level bundle, not an Eloquent-native one — confirm the ORM assumption before adoption, because it drives most integration cost.
• The requirement is application-level (field-level) encryption, not just encrypted-at-rest disk or managed-database encryption. This package encrypts individual columns and reads them back through the ORM.
• We need deterministic equality lookups on encrypted data (find user by e-mail, look up by reference) — and we accept that randomised columns are, correctly, unsearchable.
• The dataset is large enough that rotation must be batched and resumable, or we already know we will need to rotate salts periodically. The checkpoint/scope/resume machinery is the reason to pick this over hand-rolled openssl_encrypt helpers.
• We have a legacy plaintext table to retrofit and want a supported encrypt/decrypt path rather than a one-off script.
• We want a verifiable dry-run posture before touching production: --dry-run --verify reads stored columns back and fails naming the fields and row counts still on another salt version — that is the kind of pre-flight check that makes a security change approvable by a change board.

Look elsewhere when:

• We are Eloquent/Laravel-native only and not prepared to run Doctrine alongside. A first-party or Eloquent-oriented encryption package (or Laravel's built-in encrypted casts plus a custom index column) will usually be cheaper.
• We need range queries, sorting, full-text search, or aggregations on encrypted fields. Deterministic encryption solves equality only; if the product needs WHERE created_at > … on an encrypted column, the data model has to change or that field stays unencrypted.
• Only disk-level encryption or a managed KMS is required by policy — this is more moving parts than the risk warrants, including a key/salt management story we must own.
• We cannot take on the operational runbook: someone must own salt versions, in-flight checkpoint files, and the upgrade sequencing below. Without that owner, this package is a liability rather than a control.
• We are mid-rotation right now — see the upgrade caution below.

Upgrade caution for this release (flag to engineering):

• Checkpoint file format is now v2. A v1 checkpoint written by v4.6.0 is refused with a message. The documented remedy is to finish the in-flight run on the release that wrote it, or delete the file. Any production rotation in progress must be completed before upgrading — that is the one case needing a human, and it should be a release-plan line item, not a surprise.
• CheckpointService now takes the scope as its first constructor argument; setIdentifierValues() accepts integers and strings only; castIdentifierValue() may return an object. Internal API surface, but if we have subclassed or decorated these, budget upgrade work.

How to Pitch It (Stakeholders)

To executives (30 seconds): We are evaluating a PHP/Doctrine package that encrypts sensitive database columns at the application layer, with the operational tooling to change encryption keys on live data without downtime. The new release is about proving it is safe to run in production: a rotation can no longer be accidentally resumed in the wrong mode or against an out-of-date key, an interrupted run can no longer report success while losing rows, and there is now a runnable reference application that demonstrates every feature against real databases. It converts "we should rotate encryption keys" from a project into a scheduled job, and it comes with the verification steps a change board will ask for.

To engineering: Treat this as a Doctrine-level bundle with a real operational surface. The v4.7.0 work is mostly hardening of exactly the failure modes we would have written custom tooling to defend against — scope-bound checkpoints, cursor values rebuilt through their DBAL type (so bigint, date_immutable and uid identifiers round-trip correctly), batches that stop when the cursor fails to advance, --batch-size values that can no longer saturate to PHP_INT_MAX in a single batch, and checkpoint writes that are byte-counted and fsynced before the rename. The .example/ directory is the fastest route to a proof of concept: micro-kernel boot, package installed from the working tree via a path repository, full suite against real engines. Two things to plan for: checkpoint format v2 means any in-flight run finishes on v4.6.0 first, and CheckpointService's constructor signature changed, so check for subclassing. Mutation score gates are at 95, so the test suite is doing real work — but our own integration tests still need to cover our identifier types and inheritance mapping. Design constraint to internalise early: encrypted columns support exact-match lookup only, and randomised columns are deliberately unsearchable.

To security/compliance: The package provides deterministic, searchable encryption for equality lookups plus randomised encryption for non-searchable fields, versioned salts with online rotation, a pre-flight --dry-run --verify that fails naming the fields and row counts still on an old salt version, and checkpoints that refuse to be resumed outside the command, entity manager, and salt version that wrote them. Salt and key management remain ours; this gives us the mechanism and the audit trail, not the policy.