SIGNALS Docs
Reader View

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(): string
  • defaults(): array
  • rules(): array

The base SettingsDefinition also offers optional extension points:

  • types(): array for non-string storage such as boolean, integer, json, or encrypted
  • guard(array $input, SettingsService $settings): void for 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() throws InvalidArgumentException when the group already exists
  • registerMany() performs duplicate checks before mutating state, so collisions leave the registry unchanged

Lookup behavior is intentionally forgiving:

  • get($group) returns the definition object or null
  • defaults($group), types($group), and rules($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:

  • accounts
  • action-log
  • ai
  • api_cli
  • api
  • availability
  • branding
  • cache
  • colour
  • company
  • dashboard
  • email
  • finance
  • preferences
  • imports
  • integrations
  • invoices
  • localisation
  • maintenance
  • maps
  • mcp
  • nightwatch
  • notifications
  • rentals
  • payments
  • pricing
  • scheduling
  • search
  • security
  • sso
  • stock_checks
  • tax
  • uploads
  • webhooks
  • workflows

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:

  1. SettingsService falls back to registry defaults when a value is not stored in the database
  2. SettingsController resolves rules(), types(), and guard() when reading or updating a group through the API
  3. settings pages and configuration services use get(), defaults(), and types() 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() returns email
  • defaults() provides fallback values such as mailer => log
  • rules() defines per-key validation
  • types() marks keys such as smtp_password as encrypted

With that definition registered:

  • defaults('email') returns the default email settings
  • types('email') exposes storage metadata for masking and persistence
  • rules('email') gives SettingsController the 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.