Laravel Settings Laravel Package

Technical Evaluation

Architecture fit

padosoft/laravel-settings is a key/value settings store with a per-key encrypted_keys allowlist. Release 7.0.0 is a ground-up rewrite of that encryption path, and it changes the package's architectural posture in three ways a TPM should note:

• Single write path. Encryption previously lived in two independent places (the Eloquent mutator and SettingsManager::set()), with created/updated hooks re-encrypting an already-decrypted accessor value. That produced divergent on-disk shapes (one layer vs. two), wrong reads on cold cache, and plaintext written into Redis. 7.0.0 consolidates into one component (Encryption\SettingsCipher) used by both the Model and the Manager. This is a genuine correctness fix, not a cosmetic refactor.
• Envelope-based format. Values are stored as pdsenc:v1:<kid>:<payload> with cryptographic binding to the setting key and to a deployment context. The version prefix and key id make rotation and future format evolution tractable; the key/context binding means a ciphertext copied from another row or another environment will not decrypt — useful against copy-paste and cross-environment restore mistakes.
• Keyring decoupled from APP_KEY. A dedicated keyring with previous keys supports two-phase rotation without re-encrypting everything at once. This is the right shape for a production secret lifecycle, but it introduces a new secret to provision, distribute, and rotate.

The net architectural effect: the package moves from "convenience store with an optional encryption feature that didn't work" to "settings store with a managed secret lifecycle." That is a materially larger operational footprint than the version number alone suggests.

Integration feasibility

Feasible for most Laravel applications, with a defined sequence:

• Anyone who never populated encrypted_keys is functionally unaffected apart from the schema widening and the toArray()/toJson() redaction.
• Anyone who did populate it from 6.x is carrying data written by the broken dual path (single-layer, double-layer, and plaintext-fallback rows all potentially coexist). The encryption-migrate command is the intended remediation; treat it as mandatory, not optional, and rehearse it on a production-shaped copy.
• The schema change (settings.value → TEXT) is the main infrastructure dependency. Envelopes do not fit in VARCHAR(255), so the migration is unavoidable.

Technical risk

Key questions

1. What exactly constitutes "deployment context," and how is it configured per environment? What happens on a multi-region or blue/green deployment sharing one database?
2. Does the TEXT migration preserve or drop any existing index on settings.value, and what is the expected lock profile on MySQL 5.7 vs. 8.0 and on PostgreSQL?
3. Is encryption-migrate safe to run while 7.0.0 application nodes are serving traffic (dual-read tolerance), or does it require a maintenance window?
4. What is the failure mode when a kid in the envelope is not present in the keyring — hard exception, or fallback? Is there a read-only degraded mode?
5. What is the documented rollback path from 7.0.0 to 6.x after encryption-migrate has run? Is the new format readable by 6.x at all?
6. Does the keyring load once per process or per request, and how does that interact with Octane, queue workers, and config:cache?
7. Are the 27 new tests run against a real Redis/DB matrix in CI, or mocks? Specifically, is the write-path × cache-state matrix exercised against a live cache driver?

Integration Approach

Stack fit

Standard Laravel: Eloquent model, service provider, config file, artisan commands, migrations. No new runtime dependencies are implied by the release notes — the envelope uses encryptString(), so no unserialize() on stored data, which is a modest hardening win. Fits Laravel 10/11-era conventions; PHP 8.2 is the tested baseline.

Migration path

Treat this as a three-phase cutover rather than a single deploy:

1. Prepare (no behavior change). Ship the widened value column and the keyring secret to every environment. Run encryption-audit in dry-run against production to enumerate allowlisted keys that are currently plaintext, single-layer, or double-layer. This produces the migration scope and the blast radius.
2. Migrate. Run encryption-migrate (dry-run first, then apply) in a controlled window. Invalidate or version the settings cache as part of the same step — the plan must not assume old Redis entries are self-invalidating. Re-run the audit to confirm zero plaintext remains in allowlisted keys.
3. Cut over. Deploy 7.0.0 with the keyring configured, then enable any newly encrypted keys. The two-phase previous key slot is for later rotation, not for this cutover.

Compatibility

• Exception handling is preserved: new encryption exceptions extend Exceptions\DecryptException, so existing catch blocks continue to work. This is the single most important compatibility guarantee in the release and materially lowers risk for teams that already handle decryption failures.
• Applications with an empty or unused encrypted_keys list get the schema change and the redaction behavior change, and nothing else.
• Applications with populated encrypted_keys on 6.x should assume their stored data is in an indeterminate state (the release notes say as much) and plan accordingly.

Sequencing and ownership

Order of operations is constraint-driven: schema → cache handling → audit → migrate → deploy → verify. The TPM-owned decision is the freeze window: cache invalidation and keyring rollout must not straddle a settings-heavy deployment, and config:cache rebuilds must be coordinated with the rolling restart if the keyring is config-sourced. Assign a single owner for the keyring secret provisioning across all environments (including CI, queue workers, and the scheduler) before the migration is scheduled.

Operational Impact

Maintenance

Steady-state maintenance is modest but non-zero, and it is new maintenance that did not exist before because the feature was unusable. Specifically: a keyring to store and rotate, a two-phase rotation procedure to rehearse, and a periodic audit to confirm no plaintext has crept back into allowlisted keys. The three commands support this — dry-run by default, idempotent, and deliberately silent on values and lengths, which is the correct posture for a compliance-sensitive surface and should be preserved in any wrapper scripts.

Support and observability

Redaction of toArray(), toJson(), and logs is the right default, but it removes the previous (accidental) debugging channels. Support runbooks should be rewritten to lead with encryption-audit output and the exception hierarchy rather than log inspection. On-call needs to be able to distinguish, from an exception alone, between a missing kid, a context mismatch, and a plaintext-in-storage fail-closed trip — these have very different remediations. The release notes don't state whether these are separate exception types; confirm before writing the runbook.

Scaling

No meaningful per-request cost increase; envelope decryption replaces the previous path. Watch two things: the TEXT column change affects row size and any value-based index (see risk table), and the keyring must be available to every worker class — web, queue, scheduler, and any long-lived Octane process — since a missing keyring in a worker manifests as a background job failure rather than a user-visible error, which is the harder failure to notice.

Failure modes

• Fail-closed trip after upgrade — the highest-likelihood incident. Mitigated by making encryption-audit a hard gate on the deploy.
• Cold-cache inconsistency — largely eliminated by design (DB and cache now hold the same raw value), but only if the old cache is actually purged at cutover.
• Context mismatch on failover / multi-region — surfaces as decrypt failures that look like corrupted data. Needs an explicit test in the DR runbook.
• Missing keyring on a worker node — silent until the first job touches an encrypted setting.
• Rollback after migrate — the least-understood failure mode; assume 6.x cannot read 7.0.0 data and plan for forward-fix rather than rollback unless the vendor states otherwise.

Ramp-up

Low for application developers — the API is unchanged, and the redaction is transparent. Moderate for platform/SRE — keyring provisioning, cache invalidation, migration window, and rotation drill. The realistic estimate is one focused day of platform work to provision the keyring across environments and rehearse encryption-migrate on a production copy, plus a short rotation exercise to validate the previous-key path before relying on it. Budget the audit-and-migrate gate as a distinct milestone; it is where the risk actually concentrates, and it is the item most likely to be under-scoped.