Encryption Laravel Package

Technical Evaluation

Architecture fit. The package is a PHP cryptographic library with factory, registry, and encryptor abstractions that should map cleanly to Laravel’s service container and configuration model. The v1.4.0 changes are additive and opt-in, so the package can sit behind existing application services rather than forcing a re-architecture.

Integration feasibility. High. It supports PHP 8.0–8.4 and can be installed via Composer. Master key injection is explicit through the factory. If we already use Laravel’s built-in encryption, this is a parallel capability, not a drop-in replacement.

Technical risk. Crypto risk is high-consequence, but this release reduces risk. The HMAC parameter order was semantically wrong but not exploitable; the fix is opt-in as v2. There are no breaking changes. The key operational risk is that v1 and v2 ciphertext share the same wire prefix and are mutually unreadable, while a wrong-scheme read and tampering both surface as MAC failure. PHPStan level 9 improves registry typing but may break downstream static analysis if callers used methods outside the interface.

Key questions.

• Which algorithms and modes do we actually need: AES-256-GCM, SM4-CBC, ZUC? Is SM4/ZUC driven by compliance or interoperability?
• Where will master keys live: environment variables, KMS, HSM, Vault? Who owns rotation and key ceremony?
• Do we need v2 subkey derivation now, or only for new data? What is the re-encryption appetite?
• How will we persist derivation scheme version outside the ciphertext, such as a database column or envelope metadata?
• What throughput and latency do we need, and is pure-PHP ZUC acceptable for those paths?
• Do all target environments have required extensions such as ext-gmp?

Integration Approach

Stack fit. Laravel/PHP 8.0–8.4. Register the factory or manager as a singleton in a service provider and inject it via constructors. Keep configuration explicit for algorithm, mode, and derivation scheme. Avoid scattering derivation choices across call sites.

Migration path. Treat v1.4.0 as a non-breaking upgrade. Default behavior remains v1 byte-for-byte. Adopt v2 only through an explicit decision. For existing data, keep v1 read/write unless re-encryption is funded. For new data, decide whether to start on v2; if yes, store the scheme version in application metadata.

Compatibility. Existing ciphertext remains readable under the v1 default. v1 and v2 cannot decrypt each other. The public API is stable. Static analysis may now flag calls on registry returns outside the interface, so fix those during upgrade.

Sequencing.

1. Upgrade the package in a branch; run the full test suite and PHPStan.
2. Deploy with v1 default; make no data changes.
3. Add explicit configuration and observability for derivation scheme.
4. If v2 is required: define key ceremony, add per-record scheme metadata, and enable v2 for new writes only.
5. Backfill or re-encrypt selected datasets with dual-read support.
6. Only after backfill, consider v2 as default; never mix schemes without metadata.

Operational Impact

Maintenance. Low-to-moderate. The package has active release engineering: CI across PHP 8.0–8.4, PHPStan level 9, 260 tests and 4605 assertions, plus i18n verification. It still needs clear ownership for version pinning, security review, and key management runbooks.

Support. Documentation is strong. README §8 covers v1-to-v2 migration, incompatibility, and the MAC-failure ambiguity in 11 languages. The main support burden is crypto literacy and key custody, not package mechanics.

Scaling. ZUC improved to 3.55 MB/s end-to-end but remains pure PHP and far from native AES throughput. Do not position it for high-volume bulk encryption. Use AES-GCM/native paths for throughput-sensitive workloads; reserve SM4/ZUC for compliance or interoperability cases.

Failure modes.

• Wrong derivation scheme produces MAC failure indistinguishable from tampering; require metadata and runbooks.
• Lost or mishandled master keys are unrecoverable; require KMS/HSM-backed custody.
• Missing ext-gmp or extension drift causes test/runtime gaps.
• Downstream static analysis failures may appear after typed registry changes.
• Configuration drift across services can lead to mixed v1/v2 writes.

Ramp-up. Moderate. Teams must understand master key handling, derivation scheme selection, and ciphertext versioning. Plan a short internal enablement session and require design review before enabling v2 or using non-AES algorithms.

Overall TPM recommendation: adopt v1.4.0 as a low-risk, non-breaking upgrade; keep v1 as default until a funded migration plan exists; if v2 is needed, gate it behind explicit metadata, key-ceremony approval, and staged re-encryption. Do not treat ZUC as a general high-throughput cipher.