Nova Settings Laravel Package

Technical Evaluation

Architecture fit

• The package is a thin, self-contained Nova tool: no migration, no table, no custom resource. Groups and fields are declared in config/nova-settings.php using native Nova field classes; the UI is Nova's own resource chrome; persistence is a read-mutate-rewrite of .env.
• This fits exactly one architectural slot: single-tenant, non-bootstrap, non-secret scalars, edited by trusted internal admins. Mail-from identity, support inbox, maintenance copy, outbound endpoints, internal feature flags. Nothing else.
• It does not fit: multi-tenant config, any value read during container boot (APP_KEY, APP_ENV, DB_*, QUEUE_CONNECTION, LOG_CHANNEL), secrets, anything needing audit/versioning/rollback, or any environment where the .env file is not the deployment source of truth (Docker/K8s/env injection). Those are category mismatches, not configuration problems.
• The strategic consequence is that this is a time-to-change win, not a platform capability. It defers a settings CRUD screen; it does not substitute for one.

Integration feasibility

• Mechanically cheap: composer require, vendor:publish, register the tool in NovaServiceProvider::tools(), author the config. An engineer can demo the loop in an afternoon.
• The real cost is not the package, it is the prerequisite refactor: every env() call outside config/*.php must become config(), or the tool's writes are invisible once config:cache runs. Budget this explicitly — it is the difference between a useful tool and a decorative one.
• Secondary integration work: a config-cache invalidation decision in the save path or deploy hook; .env.example reconciliation in CI; backup-before-write; activity logging for author attribution; write permissions on .env for the FPM user.
• Compatibility is the open unknown: Nova 4 vs Nova 5 field API must be verified against our installed major, and the Nova::tools() authorization path vs the tool's own group/field gates should be checked in src/ before we commit.

Technical risk

• Config cache staleness — highest severity, highest frequency. Since v1.1.2 (PR #16 cache-hit optimisation) there are two caches: the package read cache and Laravel's config cache. Values can be correct in .env, correct in the UI, and stale in the app. Any cache patch changes when a value is observed, not whether it was written — that class of bug surfaces only under concurrency or in long-lived processes.
• .env is not a database. #, quotes, $, spaces, trailing backslashes and newlines are all dotenv semantics, not string data. My #1 App truncates silently. Unless the package quotes defensively, fields need ->rules('regex:/^[^#"\'\$\n]+$/').
• Secret clobbering. A Password field round-tripping ******** over the real value is the classic data-loss mode of env editors and will not appear in casual testing.
• Booleans are strings. (bool) "false" is true. Requires trueValue('true')/falseValue('false') plus FILTER_VALIDATE_BOOLEAN at read time.
• Last-write-wins concurrency. Whole-file read, single-key mutate, write back. Two admins, or an admin plus a deploy writing .env, silently loses a change.
• Supply-chain / continuity risk is material and independent of code quality. 32 stars, zero dependents, single maintainer, last release 2024-03-31. Score and opportunity signal say the same thing: low adoption maturity. Mitigation is a pinned version plus a documented exit — the contract is narrow ("write env vars"), so replacement with a ~150-line custom Nova tool or spatie/laravel-settings behind config does not touch application code.

Key questions

1. Which Nova major are we on, and does the field API in this release match it?
2. Can groups/fields be registered at runtime, or only from config? (Determines whether this survives a second team's settings.)
3. Is there a save event/failure hook we can hang cache invalidation and activity logging on, and does 1.1.2's read cache expose a public flush?
4. Where does .env actually live in each environment — file, injected, or read-only volume?
5. How is config cache invalidated after a save: package-side, an Artisan call, a deploy hook, or "we don't run config:cache here"?
6. Who is the named owner of config/nova-settings.php, and who approves a change to a production value?

Integration Approach

Stack fit

• Requires an existing Laravel Nova install (internal admin surface, not customer-facing), MySQL/Postgres-backed app, and a writable .env in at least the environments where the tool is enabled.
• Fits best where the tool is enabled in local and staging only, with production values promoted through the normal config pipeline (Vault, SSM, k8s ConfigMap). Staging becomes the review-the-diff surface — that is the pattern that scales across a team.
• Poor fit where env vars are platform-injected and .env does not exist, or where the filesystem is read-only. In those cases the tool either fails or creates a shadow .env that overrides injected values — worse than failing.

Migration path

• No data migration. This is additive; nothing in the app is rewritten except env() → config() call sites, which is a correctness improvement regardless of whether we adopt the package.
• Cleanest sequencing: do the env() → config() refactor and cache-invalidation policy first, prove them without the package, then add the package as a UI over a pipeline we already control. That order makes adoption reversible.
• Exit path is cheap by design: keep config/nova-settings.php as the single declaration point, keep all reads going through config(), and the tool can be swapped for a custom Nova resource without touching application code.

Compatibility

• Pin exactly ("stepanenko3/nova-settings": "1.1.2"). Verify the Nova major constraint explicitly; do not infer it from the README.
• Read src/ end-to-end before first deploy. It is a small package — roughly an hour — and it settles caching, quoting, save hook, and authorization questions that would otherwise be discovered in production.
• The 1.1.2 diff is internal-only (no features, no breaking changes, no config surface changes) but caching patches change observation timing; treat every bump as a staging smoke test, not a routine merge.

Sequencing

1. Week 1 — feasibility. Read src/. Answer the six key questions. Confirm Nova major and field API. Exit criterion: a written go/no-go.
2. Week 2 — prerequisite refactor. env() → config() everywhere outside config/*.php. Decide and implement cache invalidation. Add .env.example diff check to CI.
3. Week 3 — narrow pilot. One group only, low blast radius: support inbox, mail-from name, one marketing flag. Enable in local/staging. Verify the loop: save → grep MY_KEY .env (quoting intact) → fresh php artisan tinker → a second long-lived process (queue worker) → confirm the 1.1.2 cache isn't serving stale reads.
4. Week 4 — hardening before any second group. Password round-trip test on a neighbouring-field save; hostile-input test (App #1, "quoted", pass$word, trailing backslash); backup-before-write; activity logging; ->readonly() on excluded keys.
5. Later — production posture decision. Either production stays out of scope (recommended) or it is enabled behind Gate::allows('manage-settings') plus a runbook covering queue:restart and octane:reload after every save.

Operational Impact

Maintenance

• Two ongoing costs. First, ownership of the config file: someone must own config/nova-settings.php as a schema, review additions, and reconcile it against .env periodically — orphaned keys written by hand survive rewrites but are invisible in the UI, which gets messy within a year.
• Second, upgrade diligence. Bus factor 1, low stars, zero dependents. Every bump is a manual review plus a staging smoke test (save a value; read it from a freshly booted Artisan command, a queue worker, and the UI). That is roughly an hour per release — acceptable, but it must be scheduled, not assumed.
• Ongoing engineering time is low if staged correctly and high if the tool is enabled in a config-cached production environment. That single decision dominates the maintenance estimate.

Support

• Support load concentrates on "I changed it and nothing happened." Triage path is three steps and should be written into the runbook before launch: grep the file (source of truth) → fresh php artisan tinker (bypasses config cache) → the web/queue process. That localises any stale value in under a minute.
• Second support vector: "I saved and it broke." .env quoting and boolean-as-string are the usual causes. Restricting field validation up front is cheaper than supporting free-text env edits.
• Admins are internal, few, and trusted. This is not a customer-facing support surface — if it ever becomes one, the model breaks.

Scaling

• Does not scale along any axis that matters. Not multi-tenant. Not multi-node: concurrent saves across nodes are last-write-wins on a single file, and a shared package cache means a deploy or a second node can flush cached values for everyone mid-edit. Not high-concurrency: two admins saving simultaneously lose one change silently.
• Long-running processes — queue workers, Horizon supervisors, Octane workers, the scheduler — cache config at boot and do not see edits. Every settings change requires queue:restart, and octane:reload where applicable. Put this next to the Save button, not in a wiki.
• The honest ceiling: a handful of groups, a handful of editors, one environment's worth of truth. Beyond that, the correct move is a real settings store, and this package's value becomes "prototype that informed the build."

Failure modes

• Stale config (config cache, then package cache) — most likely, most confusing, fully diagnosable with the three-step triage.
• Secret clobbering — silent data loss when a Password field writes ******** back. Detect only via an explicit round-trip test.
• Truncated or corrupted values — dotenv semantics on #, quotes, $, newlines. Detect via hostile-input tests.
• Lost update — concurrent saves, or admin save racing a deploy write. Mitigated by keeping .env writes out of the deploy pipeline while the tool is enabled, plus timestamped backups into storage/.
• Write failure — permissions or read-only filesystem in containers; or a shadow .env overriding injected platform values.
• Boot-time values edited — APP_KEY rotation invalidates encrypted columns, sessions and password-reset tokens. The correct mitigation is exclusion or ->readonly(), not a warning label.
• Abandonment — maintainer stops releasing; Nova major moves on. Contained by the narrow contract and the documented exit.

Ramp-up

• Engineer: one day to a working pilot, one week to production-grade hardening. Most of that week is the env() → config() refactor, which pays off independently.
• Admin/ops user: minutes. The UI is native Nova and groups-by-blast-radius (Mail, Payments, Features, Integrations) reads correctly to a non-developer. Group by blast radius, never by vendor — grouping by vendor pushes "is it safe to touch this?" onto the person least equipped to answer.
• Organisation: the real ramp-up is policy, not training. Which keys are editable, who approves a production change, and how cache invalidation happens after a save. Settle those three in writing before the first group ships; they are the difference between a controlled convenience and an incident.

Recommendation: adopt as a staging/local, internal-ops convenience with an exact pin, a one-week hardening budget, and a named owner. Do not treat it as the settings platform; if per-tenant config, audit trail, versioning, or approval flow is on the roadmap, fund that separately and let this package cover the interim.