Laravel Foundation Laravel Package

Product Decisions This Supports

• Settings reliability as a product surface. Dotted keys (e.g. lead.default_status) now persist correctly from the admin Settings page. This is the kind of defect that silently drops configuration — a PM should treat "settings that appear to save but don't" as a data-integrity issue, not a cosmetic bug, and can now trust admin-entered config as a source of truth for downstream feature behavior.
• Extensibility of user/document metadata. UserDocument::typeLabel() and the tolerant handling of unlisted DocumentType values mean projects that add their own document types (or carry legacy rows from older schemas) can render the admin user page without patching core. This supports decisions to extend verification/KYC-style flows rather than building a parallel document store.
• Upgrade risk assessment for in-flight work. Two behavioral edges changed: the Settings view now names inputs settings[{key}], and unrecognized document types return a string instead of throwing. Teams with a forked/copied Settings view or code that relied on the exception become a planning input for the next release train.
• Build vs. buy signal. Repeated maintenance on admin settings persistence and defensive rendering of legacy enum data is exactly the undifferentiated work a package should absorb. This release strengthens the case for buying/keeping rather than maintaining an in-house admin config layer.
• Support and QA load. Both fixes address failure modes that generate support tickets ("my setting won't stick", "the user page is blank"). Reduced ticket surface is a measurable outcome for roadmap planning.

When to Consider This Package

Adopt or keep it when:

• You need persisted, admin-editable application settings with nested/dotted keys, and you want that behavior maintained upstream rather than hand-rolled.
• Your domain has user documents with an enumerated type, and you expect projects or future releases to add types outside the original enum — the new string fallback plus typeLabel() avoids crashes on old or extended data.
• You run multiple projects or tenant variants off one codebase, where legacy rows and per-project type additions are normal.
• You value non-breaking patch releases: v3.5.2 is a patch with bug fixes and one additive helper, with no migration or config changes implied.

Look elsewhere or proceed with caution when:

• You have customized or copied the Settings page view. Keys without dots still work with key-named fields, but dotted keys require renaming fields to settings[{key}] (and settings[{key}][] for multi-selects). Budget a small migration task.
• Your code catches exceptions from UserDocument::document_type to detect invalid types. That contract is gone — unrecognized values now return a string. Switch to typeLabel() for display or validate explicitly.
• You need first-class multi-language labels or rich document-type metadata; this release only guarantees a humanized label.
• Your settings requirements are environment/file-based only — the admin UI machinery may be more than you need.

How to Pitch It (Stakeholders)

For executives: This patch closes two trust-eroding defects in the admin layer — configuration that silently failed to save when keys contained dots, and a user page that could crash on older or project-specific document types. Neither adds scope or cost; both reduce support tickets and the risk of stale or wrong configuration affecting customer-facing behavior. It is a low-risk, high-value maintenance release and does not change our upgrade timeline.

For engineering: v3.5.2 is a patch. Two items need a look: (1) the Settings page now posts fields as settings[{key}] — if we forked that view, rename our fields to match to keep dotted keys saving, and use settings[{key}][] for multi-selects; key-named fields still work for keys without dots. (2) UserDocument::document_type no longer throws for values outside the DocumentType list — it returns the raw string, and the new UserDocument::typeLabel() returns a readable label for both enum and string cases. Replace any exception-based validation with typeLabel() or explicit checks. No migrations or config changes; a regression pass over the Settings page and the admin user page is sufficient.

For product: We can now rely on admin-entered settings as durable state, including namespaced keys, and we can extend document types per project without breaking the admin user view — which unblocks verification/document workflows that previously required core patches.