SIGNALS Docs

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

  1. Declare keys in signals.yaml settings[] (key, type, label required; see Manifest).
  2. Install seeds defaults into the settings group through the framework settings lifecycle.
  3. Admin UI embeds Livewire PluginSettingsForm, generated from the manifest schema, on the Plugins page (/plugins, route plugins.index), gated by plugins.manage.
  4. 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, shouldKeepEncrypted keeps the prior value when the submitted value is null, '', 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.