Encryption Laravel Package

Product Decisions This Supports

• Feature/roadmap decisions: This release supports adopting the package for multi-algorithm encryption needs (AES-256-GCM, SM4-CBC, ZUC) with HMAC-based subkey derivation, especially where Chinese cryptographic standards or regional compliance matter. The new opt-in v2 subkey derivation lets teams schedule a security-semantics correction without a flag-day migration; default v1 behavior remains byte-for-byte identical, so existing products are not disrupted.
• Build vs. buy: The release materially strengthens the “buy/adopt” case. Independent execution-level review, mutation testing of pinned vectors, a hand-written ZUC-128 cross-check against official and published vectors, PHP 8.0–8.4 CI, and PHPStan level 9 are the kind of assurance signals that are expensive to replicate in-house for a crypto library. The remaining build-vs-buy question is not “can we write this?” but “do we want to own cryptographic maintenance and review?”—usually no.
• Use cases: Laravel/PHP services needing SM4 or ZUC for regulatory or interoperability reasons; data-at-rest encryption with MAC; key-derivation workflows; teams that want typed registries ($registry->get($id) returning real types) for better static analysis. ZUC should be positioned for compliance-driven use, not high-throughput encryption, given the honest ceiling of pure-PHP ZUC versus native AES.
• Migration planning: The v1→v2 subkey migration is a product/ops decision, not just an engineering one. Because v1 and v2 ciphertexts share the same wire prefix and wrong-scheme reads and tampering both surface as MAC failures, the migration plan needs explicit metadata, dual-read strategy, or re-encryption tooling. This is a roadmap item for any team that wants the corrected derivation.
• Developer experience/roadmap: PHPStan level 9 and the AbstractRegistry template annotations reduce integration friction for Laravel teams using Larastan/PHPStan. Downstream code that relied on undocumented registry methods will now get static-analysis errors—this is a deliberate quality improvement, but it should be communicated as an upgrade note.

When to Consider This Package

• Consider adoption when: you need SM4-CBC or ZUC alongside AES-256-GCM; you operate in markets where Chinese cryptographic standards are required or preferred; you value strong CI, static analysis, mutation testing, and independent crypto review; you want an opt-in path to correct historical derivation semantics without breaking existing ciphertext; you need multilingual documentation for distributed teams.
• Look elsewhere when: your primary need is high-throughput symmetric encryption—native OpenSSL/AES will outperform pure-PHP ZUC by a wide margin; you require FIPS 140-3 or a formally validated cryptographic module; you need HSM-backed key management or hardware acceleration; you only need Laravel’s built-in AES-256-CBC/GCM encryption and have no SM4/ZUC requirement; or your organization cannot tolerate a crypto migration that requires application-level coordination because wrong-scheme and tamper failures are indistinguishable at the MAC layer.
• Due-diligence criteria: confirm the package’s production track record in your threat environment, review the README §8 migration guidance in your language, and validate that your key-management and logging practices can distinguish operational migration errors from actual tampering during the v1→v2 transition.

How to Pitch It (Stakeholders)

• To executives: This release lowers compliance and security risk for products that need Chinese cryptographic standards, with no breaking changes and no forced migration. It also demonstrates mature engineering discipline—independent crypto review, mutation testing, PHP 8.0–8.4 CI, PHPStan level 9, and 11-language documentation parity—which reduces the long-term maintenance risk of adopting the package.
• To engineering: v1.4.0 fixes a semantically reversed HMAC parameter order without changing default behavior; v2 derivation is opt-in via fromMasterKey(..., 'v2') and macDerivation: 'v2'. ZUC throughput improves from 0.3 to 3.55 MB/s end-to-end, but the team is explicit that pure-PHP ZUC is not a native-AES replacement. Registry typing improvements make downstream static analysis more useful. The upgrade is non-breaking unless you called non-interface methods on registry returns—in which case PHPStan will now correctly flag it.
• To security/ops: The v1→v2 migration must be planned carefully: ciphertexts share a prefix, and wrong-scheme reads look like MAC failures, the same as tampering. Use metadata, dual-read, or re-encryption; don’t rely on trial decryption alone in production without monitoring. The independent review and mutation tests provide good assurance, but migration observability is on us.