Laravel Settings Laravel Package

Product Decisions This Supports

• Build vs. buy for application settings storage. Adopting this package covers the "settings + secrets" layer (DB-backed settings, Eloquent integration, caching, per-key encryption) instead of building an in-house settings table plus bespoke encryption. v7 is the first version where the encrypted-settings capability is defensible as a production dependency, which changes the build-vs-buy answer for teams that previously ruled it out.
• Where customer/tenant secrets live. Enables storing third-party credentials (payment gateway keys, SMTP passwords, webhook signing secrets, per-tenant API keys) in the settings table with encryption at rest, a dedicated keyring, and an envelope format — rather than scattering them across .env, config, or a side table.
• Security & compliance roadmap items. Directly supplies evidence for controls like "secrets encrypted at rest," "key rotation supported," "no secrets in logs," and "no plaintext in cache." The encryption-audit / encryption-migrate / encryption-rotate commands (dry-run by default, idempotent, never print values) give ops a documented, repeatable runbook — useful for SOC 2 / ISO 27001 narratives and change management.
• Self-serve integrations / admin UI. Because validation and casts now apply to the plaintext value (not the ciphertext) and toArray()/toJson() are redacted, you can expose a settings screen where an admin enters an API key and get correct validation, safe API responses, and no secret leakage in the UI payload — a prerequisite for shipping any "bring your own credentials" feature.
• Secret rotation as a product commitment. Two-phase rotation via previous keys means you can commit to a rotation cadence (quarterly, on offboarding, on suspected compromise) without a maintenance window or mass re-encryption — a roadmap enabler, not just an internal hygiene task.
• Upgrade/technical-debt planning. This is a breaking release. Whether you adopt it or are already on 6.x, the work is a scoped, plannable backlog item (column migration to TEXT, keyring provisioning, ciphertext migration), not an open-ended risk.

When to Consider This Package

Consider it when:

• You store, or plan to store, credentials or other secrets in the database, and need encryption at rest with rotation rather than a one-way APP_KEY-derived scheme.
• You want the encryption keyring decoupled from APP_KEY — e.g. keys sourced from a secret manager per environment, with a deployment context bound into the ciphertext so prod data cannot be decrypted with staging keys.
• Rotation without downtime matters: you need previous keys, a migrate command, and a documented two-phase procedure.
• You need Eloquent-native ergonomics (mutators, casts, validation) on top of encryption, so feature teams don't hand-roll encrypt/decrypt paths — the v7 single-cipher-path design is the point.
• Cache correctness is a concern: DB and cache now hold the same raw value, closing the "plaintext written to Redis" class of incident.
• You are on 6.x but never populated encrypted_keys — the upgrade is low-impact by the maintainer's own statement, so it is a cheap way to get onto the supported, production-safe path.

Look elsewhere when:

• You already centralize secrets in Vault / AWS Secrets Manager / Doppler and have a policy that secrets must not live in the application database. Encryption at rest with app-held keys does not buy much against a compromised app host; don't adopt this to tick a box the secrets manager already covers.
• You only need plain, non-sensitive configuration. The keyring lifecycle, TEXT migration, and rotation runbook are real operational overhead you should not take on for a key/value table of feature flags.
• Nobody on the team will own key custody: rotation, backup, and incident response for the keyring. An unrotated keyring with no owner is worse than an honest .env — you inherit the ceremony without the benefit.
• You need per-record data keys with a KMS/HSM envelope, cryptographic tenant isolation, or FIPS-validated modules. This is an application-level keyring, not a KMS.
• You cannot absorb a breaking change now and are mid-flight on 6.x with populated data — sequence the upgrade deliberately rather than opportunistically.

How to Pitch It (Stakeholders)

For executives: The settings package we use (or are evaluating) shipped v7.0.0, which fixes a defect that made encrypted settings unusable in production on 6.x — writes through two different paths produced incompatible ciphertext, and the failure mode included writing decrypted values into Redis and into logs. v7 collapses this to one encryption path, adds a versioned envelope bound to the setting key and deployment context, moves to a dedicated keyring independent of APP_KEY, supports two-phase key rotation, fails closed on plaintext found where ciphertext is required, and redacts secrets from serialization and logs. Three audited artisan commands cover inventory, migration, and rotation, dry-run by default and never printing values. Risk is contained: teams that never populated encrypted_keys see no functional change, and the upgrade is documented in a dedicated guide with an exception hierarchy that stays backward compatible. It is a scoped, plannable upgrade that converts an open security liability into a compliance asset.

For engineering: One SettingsCipher used by both the Model and SettingsManager; envelope pdsenc:v1:<kid>:<payload> with cryptographic binding to the setting key and deployment context; encryptString() so there is no unserialize() on decrypted data. Validation and casts now run on plaintext, DB and cache hold identical raw, and accessor-side echo is gone. encryption-audit, encryption-migrate, and encryption-rotate are idempotent and dry-run by default, with no values or lengths printed. A migration widens settings.value to TEXT because an envelope does not fit VARCHAR(255). 71 tests green on PHP 8.2, including the full write-path × cache-state matrix. Breaking changes are enumerated in UPGRADE-7.0.md; existing DecryptException handlers continue to work. Action items: provision the keyring and its backups before deploy, run the audit in dry-run, then migrate.