Plugin settings
Declare plugin settings in signals.yaml, use the generated admin form, and read values via PluginContext::setting() with encrypted leave-blank semantics.
Use the package-bound PluginContext supplied to your handler for plugin operations. During framework-mediated plugin execution, a facade call targeting another package throws PluginPackageMismatchException with reason plugin_package_mismatch; core and admin calls outside a plugin scope retain their existing behaviour.
Declaration → form → read path
- Declare keys in
signals.yamlsettings[](key,type,labelrequired; see Manifest). - Install seeds defaults into the settings group through the framework settings lifecycle.
- Admin UI embeds Livewire
PluginSettingsForm, generated from the manifest schema, on the Plugins page (/plugins, routeplugins.index), gated byplugins.manage. - Read at runtime with
PluginContext::setting()or$this->context()->setting()in a lifecycle method.
$value = $context->setting('greeting', 'Hello');
// PluginBase
protected function setting(string $key, mixed $default = null): mixed
// PluginContext (hooks)
public function setting(string $key, mixed $default = null): mixed
Values are decrypted (when encrypted) and type-cast by the context settings API.
Storage group naming
plugin_ + package with "/" and "-" → "_"
Examples:
| Package | Group |
|---|---|
acme/example |
plugin_acme_example |
acme/ledger-sync |
plugin_acme_ledger_sync |
Persisted as settings()->set($group.'.'.$key, …). Encrypted keys use SettingsService type encrypted.
Setting types
Manifest-allowed types: string, integer, boolean, enum, json.
| Field | Notes |
|---|---|
options |
Required non-empty list when type: enum |
default |
Optional; seeded on install |
rules |
List of Laravel validation rule strings for the generated form |
encrypted |
Stored encrypted; blank/masked save keeps prior value |
Encrypted semantics
When encrypted: true:
- Stored via the same Crypt path as other platform secrets.
- On save,
shouldKeepEncryptedkeeps the prior value when the submitted value isnull,'', or the masked placeholder (ChannelConfigMasker::FULL_MASK). - Audits / UI show a mask, not the secret.
Ledger example (client_secret):
- key: client_secret
type: string
label: Ledger Client Secret
encrypted: true
Dual registration path
| Path | Purpose |
|---|---|
Manifest → PluginContext::setting() |
Plugin-private config + generated Plugins UI form (preferred; Ledger uses this) |
$registrar->setting(SettingsDefinition $definition) |
Also register into global SettingsRegistry |
setting(SettingsDefinition) is manifest-gated: every key in SettingsDefinition::defaults() must appear in settings[].key. Prefer the manifest-only path unless you intentionally surface keys in the core settings catalogue.
Contract: Settings Registry.
Read example
In a class-based extension, bind the installed package context first:
$context = \App\Sdk\PluginContext::forPackage('acme/ledger-sync');
$direction = (string) $context->setting('sync_direction', 'push');
Inside a hook:
$direction = (string) $context->setting('sync_direction', 'push');
Settings or a connection
Use settings for application preferences. Even encrypted settings never extend the network allowlist. Use Plugin Connections for credentials, OAuth, selected organisations and operator-configured HTTPS hosts. Core renders configuration, connect, test and disconnect controls.
Use actions for record-level operations and guarded interactive input; settings are persistent plugin configuration.