Object Encryptor Laravel Package

Getting Started

keboola/object-encryptor is not Laravel-specific — it's a standalone PHP library — so treat it as a service you register in the container rather than a facade. Start here:

1. composer require keboola/object-encryptor (2.14.2 or later — see Gotchas).
2. Publish a small config/object-encryptor.php with stack_id, kms_region, key_id (or Key Vault credentials) sourced from env. Never hardcode the ARN/vault URL.
3. Bind the encryptor as a singleton in AppServiceProvider via ObjectEncryptorFactory, passing an Aws\Kms\KmsClient (or the Key Vault client) and setStackId(). Resolve it through the container everywhere; the factory setup is expensive relative to encrypt/decrypt calls.
4. First use case: encrypting third-party OAuth refresh tokens or per-tenant API credentials before writing them to a text column. Encrypt on save in a model mutator, decrypt in an accessor or a dedicated CredentialsRepository — not both, or you'll double-encrypt.

If all you need is encrypting a plain string and you control both ends inside the same Laravel app, Crypt::encryptString() is simpler. Reach for this package when you need Keboola-compatible wrappers (component/configuration/project scoping) or KMS/Key Vault-backed keys.

Implementation Patterns

• Wrapper selection drives your data model. encryptGeneric() for anything not tied to a tenant; encryptForComponent($data, $componentId) when the ciphertext must be readable only by one component; encryptForConfiguration(...) and encryptForProject(...) when scope matters. Pick the narrowest scope up front — the ciphertext embeds the scope, so widening later means re-encrypting.
• Repository layer, not model events. Wrap encrypt/decrypt in a repository or action class. Model accessors that silently decrypt make it very easy to accidentally toArray() ciphertext or plaintext into logs and API responses.
• Pass ciphertext across boundaries. Jobs, events, and webhooks should carry the encrypted blob; the worker decrypts at the point of use. This keeps plaintext out of queue payloads and failed-job dumps.
• Rotate by re-encrypting on read. Store a key_version column alongside the ciphertext; on decrypt, if the version is stale, re-encrypt and persist. Decryption failures should fall back to a re-auth flow, not a 500.
• Test with the fake, not real KMS. The factory supports mock/in-memory clients for the test environment so your suite doesn't hit AWS. Keep a single ObjectEncryptor test helper that round-trips fixtures.
• Cache decrypted values per request in a scoped instance — decrypt once in a middleware or resolver, inject the plaintext array.

Gotchas and Tips

• 2.14.2 changes object payloads. unserialize() now runs with ['allowed_classes' => false]. The wire format is unchanged, so scalars, arrays, and strings round-trip exactly as before and no re-encryption is needed. But if you ever encrypted actual objects, decrypt*() will now hand back __PHP_Incomplete_Class instead of your type. Audit for object payloads before upgrading and convert to arrays.
• Upgrade anyway. The hardening prevents gadget-chain instantiation from a tampered ciphertext. The patch is backward compatible for the overwhelming majority of consumers — it's a one-line composer bump.
• Ciphertext is bulky. Base64 of a serialized payload plus wrapper metadata; a 40-char token becomes several hundred bytes. Use TEXT/LONGTEXT, not VARCHAR(255), and don't index ciphertext.
• Not interchangeable with Laravel's Crypt. Different key derivation and envelope. Never mix the two on the same column; pick one per field and document it.
• Decryption is all-or-nothing. A tampered or wrong-scope blob throws — catch the package exception at the boundary, log the record ID (not the blob), and degrade gracefully.
• Local/dev parity. Developers without KMS credentials will fail at bind time; provide a local wrapper or mock in AppServiceProvider keyed off the environment, or onboarding stalls on day one.
• Extension point: if your key source isn't KMS or Key Vault, implement the wrapper interface rather than forking — the ObjectEncryptor itself only orchestrates wrappers.