Encryption Laravel Package

Product Decisions This Supports

• Build vs. buy for encryption primitives: This package sits on top of paragonie/halite and now exposes symmetric authenticated encryption, authenticated public-key encryption, and anonymous public-key encryption behind Laravel-friendly configuration. That is a strong argument for buying/borrowing rather than hand-rolling envelope encryption in application code.
• Feature decisions around multi-party and asymmetric data flows: AuthenticatedPublicKeyEncryption supports two-way encrypted exchange where each side has its own secret key plus the other side’s public key, with decryption proving origin. That unlocks product capabilities such as partner integrations, signed-and-encrypted webhooks, cross-tenant data exchange, and device-to-server messaging without inventing a custom protocol.
• Write-only / one-way ingestion architectures: AnonymousPublicKeyEncryption lets a deployment encrypt with only a public key and never hold the ability to decrypt. This is directly useful for roadmap decisions around compliance-sensitive ingestion, audit log shipping, telemetry pipelines, and “collect but do not read” data flows.
• Data lifecycle and migration planning: v3.0.0 marks newly written values with key id and format, makes needsReEncrypt() return true for all pre-v3 data, and preserves backward decryption permanently. This supports decisions about re-encryption sweeps, key rotation rollouts, and how much migration debt to schedule versus defer.
• Operational safety and incident reduction: Format markers turn “wrong class / wrong key / tampered value” into explicit, named exceptions instead of misleading decryption failures. This is a product-quality decision: fewer support escalations, faster root-cause analysis, and safer key configuration through tagged prefix_secret_hex / prefix_public_hex values.
• Security posture and logging decisions: Key ids and markers in exception messages are shortened and printable, preventing key material or garbage from leaking into logs. This supports logging/observability standards and reduces the blast radius of misconfiguration.
• Engineering standards and review policy: PHPStan with spaze/phpstan-disallowed-calls (including non-timing-safe encoding rules) plus an AGENTS.md of invariants signals a maintainer willing to enforce cryptographic discipline. That is relevant to decisions about accepting AI-generated or contractor code touching encryption.
• Upgrade sequencing decisions: Older versions cannot read marked values, so any multi-deployment or multi-service architecture must be upgraded as a coordinated release before writing new data. This is a roadmap and release-coordination input, not just a library detail.

When to Consider This Package

Consider adoption when:

• You need application-level encryption in Laravel/PHP and want vetted primitives rather than custom AES/Halite wrappers.
• You have two-party or asymmetric encryption requirements: partner data exchange, mutually authenticated encrypted payloads, device-to-server flows, or public-key distribution where only some services should be able to read.
• You need write-only encryption: a service or deployment that can seal data with a public key but must never be able to decrypt it.
• You operate multiple deployments sharing stored data and can coordinate upgrades; the v3 marker format demands all writers/readers be upgraded before new writes.
• You want strong failure semantics: explicit FormatMarkerMismatchException / UnknownFormatMarkerException, named creator class and method in errors, and key-slot validation at object construction.
• You have an existing symmetric usage that must keep decrypting old ciphertext indefinitely; the package’s promise that previous-version data still decrypts is a deciding factor.
• You value static-analysis enforcement of crypto-adjacent code and have a review process that can absorb a stricter dependency.

Look elsewhere or defer when:

• You cannot coordinate a flag-day upgrade across all deployments, or you have long-lived consumers that will keep running older versions against shared data.
• Your exception handling depends on catching Halite’s InvalidMessage or InvalidNumberOfComponentsException; v3 throws new types and existing catch blocks will not catch them.
• You need key management, HSM/KMS integration, or envelope encryption with rotation orchestration out of the box; this package handles cryptographic operations and key configuration, not the full secrets lifecycle.
• You require format stability with no migration work; needsReEncrypt() returning true for everything written before v3 means a re-encryption sweep is now on your roadmap, and rows created with encryptWithAd() must be re-encrypted with the correct additional data.
• You are on a PHP/Halite version below paragonie/halite 5.1+ or cannot adopt that bump.
• Your use case is transport security only; TLS, signed URLs, or managed cloud KMS may be simpler and cheaper than application-level encryption.
• You need streaming or very large payload encryption; this is message/value-oriented, not a file-encryption subsystem.

How to Pitch It (Stakeholders)

To executives: This release turns a solid symmetric-encryption utility into a broader data-protection capability. We can now support two-party encrypted exchange and write-only data ingestion without building custom cryptography, which reduces engineering risk and shortens time-to-market for partner and compliance-sensitive features. The main cost is a coordinated upgrade: every deployment that reads or writes shared encrypted data must move to v3 before new data is written, and we should schedule a re-encryption sweep. That is a bounded, one-time migration with permanent backward decryption guarantees.

To engineering: v3.0.0 adds AuthenticatedPublicKeyEncryption and AnonymousPublicKeyEncryption, both configured with the same prefix_hex style as symmetric keys, with tagged prefix_secret_hex / prefix_public_hex values recommended so mis-pasted keys fail at construction. Stored values now carry a format marker and key id ($keyId$SymV1$..., SymAdV1, AuthV1, AuthAdV1, AnonV1), which are covered by decryption verification except in AnonymousPublicKeyEncryption. Mixed-up values throw FormatMarkerMismatchException or UnknownFormatMarkerException; audit existing catch blocks for Halite’s InvalidMessage / InvalidNumberOfComponentsException. needsReEncrypt() now returns true for all pre-v3 values, so the existing re-encryption sweep becomes the migration path; rows from encryptWithAd() must be re-encrypted with the row’s additional data. Bump paragonie/halite to 5.1+. Upgrade all deployments before writing marked values, since older versions cannot read them. Exception messages now shorten and sanitize key ids/markers to keep key material out of logs, and PHPStan with spaze/phpstan-disallowed-calls plus AGENTS.md invariants now gate contributions.

To security/compliance: The package now enforces correct key placement at construction, binds key id and format marker into authenticated decryption, and reduces leakage through logs. Backward compatibility is explicit: everything written by prior versions still decrypts, and the “key id not protected against tampering” caveat is limited to old-format values once migration completes. The remaining operational obligation is to complete the re-encryption sweep and to sequence the multi-deployment upgrade correctly.