Settings Registry
Contract for registering settings groups, their defaults, validation rules, and type metadata.
Overview
App\Services\SettingsRegistry is the registry of settings-group definitions that drives SettingsService, SettingsController, and the current settings UI.
Each registry entry is a SettingsDefinition object. Core binds the registry as a singleton in SettingsServiceProvider and registers the framework's shipped settings groups there.
Public surface
| Method | Purpose |
|---|---|
register() |
Register one SettingsDefinition instance |
registerMany() |
Register multiple definitions atomically |
get() |
Return a definition for one group or null |
all() |
Return the keyed definition map |
has() |
Check whether a group exists |
defaults() |
Return the group's default values or [] |
types() |
Return the group's type declarations or [] |
rules() |
Return the group's validation rules or [] |
Accepted definition shape
The accepted registration value is a concrete subclass of App\Settings\SettingsDefinition.
The contract requires:
group(): stringdefaults(): arrayrules(): array
The base SettingsDefinition also offers optional extension points:
types(): arrayfor non-string storage such asboolean,integer,json, orencryptedguard(array $input, SettingsService $settings): voidfor write-time invariants after validation passes
The registry key is the group's group() string, such as email, security, api, or pricing.
Identity, collisions, and lookup behavior
Only one definition may be registered per group.
register()throwsInvalidArgumentExceptionwhen the group already existsregisterMany()performs duplicate checks before mutating state, so collisions leave the registry unchanged
Lookup behavior is intentionally forgiving:
get($group)returns the definition object ornulldefaults($group),types($group), andrules($group)return[]for unknown groups
Grouping, ordering, and current core registrations
This registry is group-oriented rather than category-oriented. It does not expose a secondary grouping API.
all() returns an associative map keyed by group name. The current registration order comes directly from SettingsServiceProvider.
Core registers these settings groups:
accountsaction-logaiapi_cliapiavailabilitybrandingcachecolourcompanydashboardemailfinancepreferencesimportsintegrationsinvoiceslocalisationmaintenancemapsmcpnightwatchnotificationsrentalspaymentspricingschedulingsearchsecurityssostock_checkstaxuploadswebhooksworkflows
Representative examples:
| Group | Current purpose | Example type behavior |
|---|---|---|
accounts |
Measured expected-version transition window and reversible enforcement | boolean require_expected_version (default false) |
email |
Mail transport and sender configuration | smtp_password is encrypted |
security |
Password and login policies | integer and boolean fields |
api |
API-facing operational settings | mixed validation rules and defaults |
branding |
Brand colours and company logo | four #RRGGBB regex-validated colours plus a boolean logo flag |
colour |
Availability grid and diary phase colours | hex fills, integer availability.warning_threshold (default 2) and availability.short_threshold (default 0: free below it is short); rental status colours stay on list-entry metadata |
Runtime consumption
Current framework consumers read the registry in three different ways:
SettingsServicefalls back to registry defaults when a value is not stored in the databaseSettingsControllerresolvesrules(),types(), andguard()when reading or updating a group through the API- settings pages and configuration services use
get(),defaults(), andtypes()to drive UI and runtime behavior
Updating settings through the API currently dispatches the settings.updated webhook event after the controller persists and masks the response payload. For email, sending a masked placeholder keeps the stored secret, and changing a connection field (such as smtp_host or ses_region) without supplying its secret clears the retained secret.
Worked example
This is the current registration shape for one definition object:
$registry->register(new EmailSettings);
That single object contributes all of the following group-level contract data:
group()returnsemaildefaults()provides fallback values such asmailer => logrules()defines per-key validationtypes()marks keys such assmtp_passwordasencrypted
With that definition registered:
defaults('email')returns the default email settingstypes('email')exposes storage metadata for masking and persistencerules('email')givesSettingsControllerthe validation schema for partial updates
Organisation view defaults
The settings API and admin screens read and write the same keys. View defaults apply only to people who have not saved a personal choice.
| Group | Key | Accepted values | Install default |
|---|---|---|---|
dashboard |
default_view |
briefing, command, board |
briefing |
scheduling |
calendar_default_view |
planner, day-first |
planner |
scheduling |
activities_default_view |
inbox, my-day |
my-day |
Read with GET /api/v1/settings/dashboard or GET /api/v1/settings/scheduling. Reads require settings.view and either settings:read or the matching group ability, such as settings:read:dashboard. The index includes only groups granted to the token. Group abilities apply to personal access tokens and OAuth connection tokens alike. Reads mask encrypted and credential-shaped values.
Send a partial object to PUT /api/v1/settings/{group} or PATCH /api/v1/settings/{group}. Writes require settings.manage and settings:write; invalid or null view names return 422 without changing settings. Each changed key records a settings.updated audit entry, and the response uses the standard {data, meta} envelope. Dashboard defaults appear in DashboardSettingsData; scheduling defaults appear in SchedulingSettingsData, with the allowed view values in their schemas.
{"settings":{"default_view":"command"}}
For scheduling, send {"settings":{"calendar_default_view":"day-first","activities_default_view":"inbox"}}. The dashboard setting is also available under Admin → Settings → General; calendar and activity defaults are under Admin → Settings → Scheduling. These writes leave personal preferences in place.
MCP clients use describe-endpoint and execute-endpoint for api.v1.settings.index, api.v1.settings.show, and api.v1.settings.update, supplying path_params.group and the same settings body. The tools apply the API's permissions, validation and audit behavior.
Imported cash posting lock
The finance group includes nullable posting_lock_date (Y-m-d, strictly before today). settings.manage may close or reopen historical imported cash dates. The policy reads it at call time; today postings retain their current behavior.