Plugin actions and forms
Core-rendered interactive forms, guarded record pickers and action handlers.
Overview
SDK 2.1 renders declared actions through core Flux controls. Plugins supply configuration and PHP handlers; no plugin views or JavaScript are required. Actions always execute as the signed-in user, never an integration identity.
Declare an action
sdk: "^2.1"
actions:
- key: acme.ledger.link
label: Link contact
permission: accounts.view
record: accounts
slots: [account.detail.header_actions]
confirm: {title: Link contact?, body: Existing links will be replaced., button: Link}
fields:
- {name: contact, type: select, label: Contact, options_from: provider, required: true}
- {name: note, type: textarea, label: Note, rules: ['max:500']}
- {name: token, type: text, label: Reference, sensitive: true}
Keys are vendor-prefixed and unique. Permission must be registered by core or declared in the plugin. record names an entity or slot record type; the host supplies its locked context. Only matching detail header-action slots may place it. Actions without record context can appear on pages:
pages:
- key: sync
title: Sync
sections:
- {type: form, key: inline, action: acme.ledger.sync}
- {type: actions, key: buttons, actions: [acme.ledger.sync]}
form is inline; actions opens a core modal. Declare every referenced action. Section keys, when supplied, are unique lowercase slugs. An unregistered handler is disabled as “Unavailable”, produces a boot warning, and fails signals:plugin check --wire.
Fields and options
Supported types are text, textarea, integer, number, boolean, date, datetime, email, HTTPS-only url, select, record and connection. There is no hidden type. Fields accept name, label, help, placeholder, required, default, rules and sensitive.
Rules are limited to required, nullable, min:n, max:n, between:a,b, in:…, date, after:…, before:…, alpha_dash, email, url, integer, numeric and boolean. Database-probing and regular-expression rules are rejected.
A select uses static options: {key: Label} or options_from: provider. Register an ActionOptionsProvider with actionOptions($actionKey, $field, $provider). Its search(PluginContext, PluginActionInput, string $term): array returns ActionOption values, capped at 50. Its resolve(PluginContext, PluginActionInput, string $value): ?ActionOption must recognize the exact submitted value. Labels and descriptions are plain escaped text.
Record fields declare entity, label_field, search_field and optional fixed filters. The plugin must declare both read and list access, readable label/search fields and a search filter supporting contains. Search returns at most 20 records as the signed-in user. Submission re-reads the chosen ID through guarded access. Connection fields name a declared connection; only connections visible to the current user can be selected, and selection is checked again on submit.
Register and return a result
use App\Sdk\Actions\PluginActionInput;
use App\Sdk\Actions\PluginActionResult;
use App\Sdk\PluginContext;
$registrar->action('acme.ledger.link', function (PluginContext $context, PluginActionInput $input): PluginActionResult {
$account = $input->record->read($context);
$contact = $input->get('contact');
// Apply the declared integration operation here.
return PluginActionResult::success('Contact linked');
});
$registrar->actionSlot('account.detail.header_actions', 'acme.ledger.link');
Input exposes action, validated values, optional typed record and UUID submissionId. Integer and record/connection IDs become integers, numbers become floats, booleans become booleans, and dates become CarbonImmutable. Use the submission ID as an external idempotency key where appropriate.
Return success($message, $redirectPage = null, $refresh = true), invalid($fieldErrors, $message = null) or failed($message). A redirect must name a declared page in the same package. Core displays escaped messages and field errors. Exceptions and other return values produce a generic failure, with diagnostics in the application log.
Security and testing
Livewire uses the web route's CSRF protection. Package, action, record context and submission identity are locked. Core checks action permission on render and submit, checks the host record's view policy, validates fields, resolves selected values, and limits each tenant/user/action to 30 submissions per minute. An atomic ten-minute cache guard returns the first result for repeated submissions; concurrent attempts cannot invoke the handler twice. A failed result is also retained, so a deliberate retry should open a fresh form. Cache expiry is not a durable external idempotency guarantee.
Audit events plugin.action.executed and plugin.action.denied contain non-sensitive validated values and record {type, id}, plus package/action/submission/user metadata. Provider requests and handlers run inside package execution scope. Core never fetches URL field values.
In the framework sandbox, PluginTestCase::submitAction($actionKey, $values, $record = null, $as = null) uses the same guarded runner. Sign in with an ordinary user or owner first. Assert returned status and observable effects, including replays and revoked access.