- How do I install spaze/encryption in a Laravel project?
- Install it with Composer using composer require spaze/encryption. The library is dependency-light and does not require a Laravel service provider or configuration file. You can call its static encrypt and decrypt methods directly from controllers, jobs, or services, keeping passphrases in environment variables or a secret manager.
- Does spaze/encryption work with Laravel 10 and Laravel 11?
- spaze/encryption is framework-agnostic PHP, so it works alongside any Laravel version that supports its PHP and ext-sodium requirements. Version 3 requires Halite 5.1 or newer, so check Composer resolution and your PHP extension setup early. There is no Laravel-specific version constraint, but you should run your own tests on the Laravel version you deploy.
- How do I encrypt and decrypt strings with spaze/encryption?
- The API is intentionally minimal: you pass a plaintext string and a passphrase to encrypt, and the resulting ciphertext is self-describing and versioned. To decrypt, pass the ciphertext and the same passphrase back to the library. Decryption fails loudly with an exception if the payload was modified or corrupted, rather than returning garbage.
- How should I manage encryption keys or passphrases with spaze/encryption in Laravel?
- Use password-based keys derived from passphrases, with a per-message salt handled by the library. Store passphrases in Laravel's environment file or a dedicated secret manager, never in source control. For asymmetric key modes in v3, use the tagged prefix_secret_hex and prefix_public_hex forms so a key placed in the wrong slot fails at object creation.
- What happens if someone tampers with a spaze/encryption ciphertext?
- The library uses authenticated symmetric encryption, so modified or corrupted ciphertexts are detected during decryption. Instead of returning garbage plaintext, decryption throws an exception that your application can catch and handle. This makes it suitable for protecting stored fields and data exchanged between services.
- Is spaze/encryption backward compatible with data encrypted by older versions?
- Version 3 can read both older and new ciphertexts, and its self-describing format is designed for future algorithm changes. However, older package versions cannot read the marked format that v3 writes. That means every service, queue worker, and job that shares ciphertext must be upgraded before any writer starts producing v3 values.
- How do I migrate existing encrypted data to spaze/encryption v3 in Laravel?
- Treat it as a coordinated format migration rather than a routine Composer update. Inventory every reader and writer of encrypted data, upgrade all readers to v3 first, then enable v3 writes and run the needsReEncrypt() sweep. For rows written with encryptWithAd(), re-encrypt with the correct row additional data or decryption will fail.
- Which exceptions should I catch when decrypting with spaze/encryption?
- In v3, format errors can throw FormatMarkerMismatchException and UnknownFormatMarkerException, which replace some Halite exceptions for format problems. You should also keep handling Halite's InvalidMessage and InvalidNumberOfComponentsException where your code previously caught them. Review all catch blocks that wrap decryption before rolling out v3.
- Can spaze/encryption handle public-key or asymmetric encryption?
- Yes, v3 adds AuthenticatedPublicKeyEncryption for two-party exchanges where both sides encrypt and decrypt and need sender authentication. It also adds AnonymousPublicKeyEncryption for write-only producers that hold only a public key and must never decrypt. Provision, store, and rotate key pairs carefully, because a missing private key makes anonymous ciphertext unrecoverable by design.
- How does spaze/encryption compare to Laravel's Crypt facade or Halite?
- Laravel's Crypt facade is convenient for app-level encryption using the application key, but it is tied to Laravel's configuration and key model. spaze/encryption is a small standalone library with password-derived keys, versioned ciphertexts, explicit tamper detection, and v3 public-key modes. Halite 5.1+ is the underlying cryptographic dependency for v3, so some teams may use Halite directly if they need lower-level control.