Plugin SDK
Working Plugin SDK guide for Signals extensions — App\Sdk stability boundary, lifecycle overview, and links to dedicated plugin guides.
Overview & architecture
Signals plugins are Composer packages that extend the platform without modifying core code, core tables, or core migrations. Every plugin declares a static signals.yaml manifest. The framework validates that declaration before any plugin code runs, then mediates data access, HTTP, storage, and UI injection through the documented stable SDK surface.
No example plugins ship in the repository — a fresh install starts with an empty Plugin Manager. The in-repo references you can read are the plugin test fixture packages (acme-example is the complete minimal shape) and the standalone valid manifest fixture. These guides use the fictional package acme/ledger-sync as a worked example. A plugin installed through Composer lives under vendor/ and is discovered by the same SDK runtime as any other third-party package.
Lifecycle
discover → validate → install → enable → boot → disable → uninstall
| Phase | What runs |
|---|---|
| Discover | PluginDiscovery scans Composer installed.json (extra.signals.plugin) and local packages under plugins/ — including vendor-nested plugins/{vendor}/{name}/. |
| Validate | PluginManifest::fromYamlFile() parses YAML and runs ManifestValidator. |
| Install | PluginLifecycleManager::install() creates the plugins row, runs guarded migrations, seeds permissions + settings defaults + notification types, calls PluginBase::install(). Status → installed. |
| Enable | Marks status enabled and calls PluginBase::enable(). Takes effect on the next application boot — the manager does not hot-boot. |
| Boot | PluginServiceProvider loads enabled packages (local PSR-4 via PluginClassLoader), scopes a PluginRegistrar, calls register() then boot(), then bridges Laravel string events and AuditableEvent → plugin Event hooks. |
| Disable | Soft-disable: status disabled, PluginBase::disable(). Migrations, data, and permissions are retained. |
| Uninstall | PluginBase::uninstall(), remove settings + permissions, roll back plugin migrations, delete the row. |
Version preflight runs before migrations, class loading, lifecycle hooks, or runtime registration. Dependency version checks include enabled and installed-disabled plugins. Install and update may use an installed-disabled dependency, but enable and boot require every dependency to be enabled. Conflicts apply only to enabled plugins. Workflow extension identities remain reserved until the owning plugin is uninstalled, including while it is disabled. Disable and uninstall fail while an enabled plugin depends on the target; an update fails when its new version breaks an enabled dependant's constraint.
Install and update are two-step review operations. Signals builds a tenant-specific plan from the exact staged package bytes, manifest bytes, distribution artifact digest, dependency state, current plugin revision, provenance, and normalized capability set. The plan expires after 15 minutes. The lifecycle operation runs only when the operator confirms the exact plan hash. Signals records the accepted capability set, actor, time, plan hash, staged-package hash, manifest hash, and artifact hash in plugins.capability_grants. Any byte, dependency, plugin-state, provenance, or capability change invalidates the confirmation. Signals reauthorizes the actor after it acquires one tenant-qualified atomic lifecycle lock.
Capability consent is an accountable declaration, not a sandbox. Installed plugin PHP code runs inside the Signals process. Only install code from a source that you trust.
SDK versions
The SDK version is 2.1.1: MAJOR changes break the stable surface, MINOR changes add features or change experimental APIs, and PATCH covers other changes. Use sdk: "^2.1" for the new APIs. The separate signals_version: "^1.0" constraint describes the host application version; the two versions are independent. The host checks these constraints during install, enable, update, registry selection and boot.
Stability boundary
The stable boundary is App\Sdk\* excluding anything marked @internal, plus the explicit SdkSurface::STABLE_CLASSES entries below. Use PluginContext for mediated core data access. Internal registries and dispatchers are framework implementation details, not plugin dependencies.
New register() implementations may type-hint App\Sdk\Contracts\PluginRegistrar. The concrete App\Services\Plugins\PluginRegistrar parameter remains supported in 1.x, so existing subclasses keep working.
Stable classes
| Class | Support |
|---|---|
App\Sdk\Actions\PluginActionInput |
Explicit stable surface |
App\Sdk\Actions\PluginActionResult |
Explicit stable surface |
App\Sdk\Actions\ActionOption |
Explicit stable surface |
App\Sdk\Actions\ActionOptionsProvider |
Explicit stable surface |
App\Sdk\Ui\MapMarker |
Explicit stable surface |
App\Sdk\Ui\MapMarkerStatus |
Explicit stable surface |
App\Sdk\Jobs\PluginJob |
Explicit stable surface |
App\Sdk\Manifest\ManifestSchedule |
Explicit stable surface |
App\Sdk\Testing\PluginTestCase |
Explicit stable surface |
App\Sdk\Testing\MakesPluginManifests |
Explicit stable surface |
App\Sdk\Testing\FakesPluginHooks |
Explicit stable surface |
App\Sdk\Testing\RecordingPluginHookDispatcher |
Explicit stable surface |
Psr\Log\LoggerInterface |
Explicit stable surface |
App\Models\Warehouse |
Explicit stable surface |
App\Sdk\Logging\PluginLogger |
Explicit stable surface |
App\Sdk\Manifest\ManifestDataAccess |
Explicit stable surface |
App\Contracts\CalculationStrategy |
Explicit stable surface |
App\Contracts\CostApportionmentStrategyContract |
Explicit stable surface |
App\Contracts\Currency\ExchangeRateProvider |
Explicit stable surface |
App\Contracts\Documents\DocumentDataResolver |
Explicit stable surface |
App\Contracts\Documents\PdfDriver |
Explicit stable surface |
App\Contracts\Exports\ExportableModelContract |
Explicit stable surface |
App\Contracts\Imports\ImportableModelContract |
Explicit stable surface |
App\Contracts\Imports\PlanTemplateContract |
Explicit stable surface |
App\Contracts\Imports\Transform |
Explicit stable surface |
App\Contracts\Imports\TransformContract |
Explicit stable surface |
App\Contracts\Notifications\ChannelDriver |
Explicit stable surface |
App\Data\Notifications\ChannelConfigFieldData |
Explicit stable surface |
App\Data\Notifications\ChannelSendData |
Explicit stable surface |
App\Data\Notifications\ChannelTestResultData |
Explicit stable surface |
App\Data\Notifications\TestChannelProviderData |
Explicit stable surface |
App\Contracts\Notifications\DeliveryTrackingResolver |
Explicit stable surface |
App\Contracts\Notifications\RecipientResolver |
Explicit stable surface |
App\Contracts\Payments\PortalPaymentDriver |
Explicit stable surface |
App\Contracts\Pricing\AgreedPriceValidator |
Explicit stable surface |
App\Contracts\Pricing\DiscountCriteriaPredicate |
Explicit stable surface |
App\Contracts\Pricing\DiscountSource |
Explicit stable surface |
App\Contracts\RateModifier |
Explicit stable surface |
App\Contracts\Tax\TaxResolver |
Explicit stable surface |
App\Contracts\Workflows\WorkflowHandler |
Explicit stable surface |
App\Events\Flightcases\BeforeFlightcaseDispatched |
Explicit stable surface |
App\Events\Flightcases\BeforeFlightcaseDissolved |
Explicit stable surface |
App\Events\Flightcases\BeforeFlightcaseItemTransferred |
Explicit stable surface |
App\Events\Flightcases\BeforeFlightcasePacked |
Explicit stable surface |
App\Events\Flightcases\BeforeFlightcaseRepack |
Explicit stable surface |
App\Events\Flightcases\BeforeFlightcaseSealed |
Explicit stable surface |
App\Events\Flightcases\FlightcaseDispatchedLifecycle |
Explicit stable surface |
App\Events\Flightcases\FlightcaseDissolved |
Explicit stable surface |
App\Events\Flightcases\FlightcaseItemTransferred |
Explicit stable surface |
App\Events\Flightcases\FlightcasePacked |
Explicit stable surface |
App\Events\Flightcases\FlightcaseRepackStarted |
Explicit stable surface |
App\Events\Flightcases\FlightcaseSealed |
Explicit stable surface |
App\Guards\Rentals\Contracts\TransitionRule |
Explicit stable surface |
App\Models\User |
Explicit stable surface |
App\Sdk\Columns\PluginColumnDefinition |
Explicit stable surface |
App\Sdk\Contracts\Plugin |
Explicit stable surface |
App\Sdk\Contracts\PluginRegistrar |
Explicit stable surface |
App\Sdk\DataTables\PluginDataTableDefinition |
Explicit stable surface |
App\Sdk\Data\PluginDataException |
Explicit stable surface |
App\Sdk\Discovery\DiscoveredPlugin |
Explicit stable surface |
App\Sdk\Discovery\PluginDiscoveryException |
Explicit stable surface |
App\Sdk\Events\PluginEventException |
Explicit stable surface |
App\Sdk\Hooks\HookType |
Explicit stable surface |
App\Sdk\Hooks\HookValidatorVerdict |
Explicit stable surface |
App\Sdk\Hooks\PluginEventPayload |
Explicit stable surface |
App\Sdk\PluginPrincipalException |
Stable integration identity failure reason. |
App\Sdk\Connections\PluginConnection |
Scoped connection credentials and HTTP handle. |
App\Sdk\Connections\PluginConnectionException |
Stable connection failure reason. |
App\Sdk\Connections\ConnectionTestResult |
Connection tester outcome. |
App\Sdk\Hooks\PluginEventRef |
Entity, id and optional revision in a version 2 event. |
App\Sdk\Hooks\PluginHookRegistration |
Explicit stable surface |
App\Sdk\Http\PluginHttpClient |
Explicit stable surface |
App\Sdk\Http\PluginHttpException |
Explicit stable surface |
App\Sdk\Lifecycle\PluginLifecycleException |
Explicit stable surface |
App\Sdk\Lifecycle\PluginUploadException |
Explicit stable surface |
App\Sdk\Manifest\ManifestChannelDriver |
Explicit stable surface |
App\Sdk\Manifest\ManifestDataTable |
Explicit stable surface |
App\Sdk\Manifest\ManifestEvent |
Explicit stable surface |
App\Sdk\Manifest\ManifestHook |
Explicit stable surface |
App\Sdk\Manifest\ManifestNav |
Explicit stable surface |
App\Sdk\Manifest\ManifestNavItem |
Explicit stable surface |
App\Sdk\Manifest\ManifestNotification |
Explicit stable surface |
App\Sdk\Manifest\ManifestNotificationTemplate |
Explicit stable surface |
App\Sdk\Manifest\ManifestPage |
Explicit stable surface |
App\Sdk\Manifest\ManifestPageSection |
Explicit stable surface |
App\Sdk\Manifest\ManifestSetting |
Explicit stable surface |
App\Sdk\Manifest\ManifestSlot |
Explicit stable surface |
App\Sdk\Manifest\ManifestTool |
Explicit stable surface |
App\Sdk\Manifest\ManifestToolArg |
Explicit stable surface |
App\Sdk\Manifest\ManifestValidationException |
Explicit stable surface |
App\Sdk\Manifest\ManifestValidator |
Explicit stable surface |
App\Sdk\Manifest\ManifestWorkflowCondition |
Explicit stable surface |
App\Sdk\Manifest\ManifestWorkflowHandler |
Explicit stable surface |
App\Sdk\Manifest\ManifestWorkflowTrigger |
Explicit stable surface |
App\Sdk\Manifest\PluginManifest |
Explicit stable surface |
App\Sdk\Nav\PluginNavGroup |
Explicit stable surface |
App\Sdk\Nav\PluginNavItem |
Explicit stable surface |
App\Sdk\Nav\PluginPageDefinition |
Explicit stable surface |
App\Sdk\Notifications\PluginNotificationException |
Explicit stable surface |
App\Sdk\PluginBase |
Explicit stable surface |
App\Sdk\PluginContext |
Explicit stable surface |
App\Sdk\PluginPackageMismatchException |
Explicit stable surface |
App\Sdk\PluginRegistrarException |
Explicit stable surface |
App\Sdk\Recent\PluginRecentException |
Explicit stable surface |
App\Sdk\SdkSurface |
Explicit stable surface |
App\Sdk\Signals |
Deprecated in 1.x; use PluginContext |
App\Sdk\Slots\PluginTab |
Explicit stable surface |
App\Sdk\Slots\SlotComponentType |
Explicit stable surface |
App\Sdk\Slots\SlotComponentCatalogue |
Explicit stable surface |
App\Sdk\Slots\SlotDefinition |
Explicit stable surface |
App\Sdk\Storage\PluginStorage |
Explicit stable surface |
App\Sdk\Storage\PluginStorageException |
Explicit stable surface |
App\Sdk\Tools\ToolDefinition |
Explicit stable surface |
App\Services\DemandSourceDefinition |
Explicit stable surface |
App\Services\Imports\Plans\ImportPlanTemplateDefinition |
Explicit stable surface |
App\Services\Navigation\NavigationItem |
Explicit stable surface |
App\Services\Notifications\MergeFieldRenderContext |
Explicit stable surface |
App\Services\Plugins\PluginRegistrar |
Explicit stable surface |
App\Services\Shortages\ShortageResolverDefinition |
Explicit stable surface |
App\Settings\SettingsDefinition |
Explicit stable surface |
App\Views\Column |
Explicit stable surface |
App\Data\Notifications\ChannelOAuthData |
Notification channel contract or value object. |
App\Contracts\Notifications\HasChannelOAuth |
Notification channel contract or value object. |
App\Sdk\Http\ChannelOAuth |
Inbound callback signature verifier. |
App\Data\Notifications\ChannelSendResult |
Notification channel contract or value object. |
App\Data\Notifications\ChannelAddressFieldData |
Notification channel contract or value object. |
App\Data\Notifications\ChannelRecipientData |
Notification channel contract or value object. |
App\Contracts\Notifications\ResolvesChannelAddress |
Notification channel contract or value object. |
App\Contracts\Notifications\NormalizesChannelAddress |
Notification channel contract or value object. |
App\Contracts\Notifications\VerifiesChannelAddress |
Notification channel contract or value object. |
App\Contracts\Notifications\VerifiesInboundRequest |
Notification channel contract or value object. |
App\Sdk\Http\ChannelDeliveryException |
Inbound callback signature verifier. |
App\Sdk\Http\HmacBodyVerifier |
Inbound callback signature verifier. |
App\Sdk\Http\HmacUrlVerifier |
Inbound callback signature verifier. |
App\Sdk\Http\HeaderSecretVerifier |
Inbound callback signature verifier. |
App\Sdk\Manifest\ManifestRoute |
Inbound callback signature verifier. |
App\Sdk\Slots\SlotContext |
SDK 2.1 typed contract. |
App\Sdk\Slots\SlotContextException |
SDK 2.1 typed contract. |
App\Sdk\Manifest\ManifestConnection |
SDK 2.1 typed contract. |
App\Sdk\Manifest\ManifestConnectionField |
SDK 2.1 typed contract. |
App\Sdk\Manifest\ManifestConnectionOAuth |
SDK 2.1 typed contract. |
App\Sdk\Manifest\ManifestConnectionOrganisations |
SDK 2.1 typed contract. |
App\Sdk\Manifest\ManifestAction |
SDK 2.1 typed contract. |
App\Sdk\Manifest\ManifestActionField |
SDK 2.1 typed contract. |
App\Sdk\Manifest\ManifestActionConfirm |
SDK 2.1 typed contract. |
App\Sdk\Manifest\ManifestIntegrationPrincipal |
SDK 2.1 typed contract. |
No plugin-shipped views
Plugins never ship Blade views. UI extension is config-driven: declare a slot in the manifest, then register a core Blade/Livewire component name plus a data callable (or trusted HTML) via PluginRegistrar::slot().
Plugin guides
| Guide | Topic |
|---|---|
| Getting started | 10-minute local plugin quickstart |
| Plugin registry | Install published plugins, understand tiers, Cloud rules, and provenance |
| Folder structure | Canonical package tree |
| Manifest reference | Complete signals.yaml + validation messages |
| DataTable SDK | Shared DataTable API, column config schema, datatable() / datatableSlot(), live demo |
| Hooks | HookType, PluginContext, bridges, failure isolation |
| Events | EventRegistry, visibility, registering names |
| Registries & resolvers | Full PluginRegistrar surface |
| Settings | Manifest settings, encryption, PluginContext::setting() |
| Storage & HTTP | PluginStorage + PluginHttpClient |
| Data access | Guarded read / update / operation |
| Data models | Entity catalogue + field reference |
| UI | Slots, modals, nav groups + pages, palette, recents, notifications, admin form |
| Channel providers | Vendor-neutral notification ChannelDriver plugins, channel_drivers manifest, lifecycle |
| Documents | Document type / resolver / PDF / template seams |
| Import / export | Shipped registrar seams, contracts and examples |
| Keys | Key grammar and namespaces |
| Troubleshooting | Validation issues, boot failures and diagnostics |
| Hook payloads | Published payloads and handler arguments |
| Event catalogue | Core event names and consumer visibility |
| Slot components | Supported components and props |
| Runtime | Context, logging, settings and data visibility |
| Actions and forms | Core-rendered interactive actions and guarded selections |
| Integration identities | Consented background actors, scope and revocation |
| Jobs and schedules | Declared schedules and scoped queued jobs |
| Data tables | Plugin table definitions and providers |
| Notification templates | Declared mail templates and validation |
| Upgrades | Updates, consent and migrations |
| Packaging | Archives, registry entries and signatures |
| Inbound requests | Current inbound HTTP limitations |
| Sandbox app | Local framework checkout, package checks and CI |
| Testing | Public test harness and package runner |
| LLM / agent guide | Copy-paste agent instructions |
| Examples | Separately installed examples + the core acme-example test fixture |
| Coming soon | Deferred / aspirational roadmap only |
Plugin actions: list, create, install, registry:list, registry:install, registry:refresh, remove, enable, disable, check, test.
Plugin options: --path, --force, --accept-capabilities, --wire, --json, --filter, --compact.
Related commands: signals:plugin-cache, signals:plugin-cache-clear, signals:plugin-schema, signals:events, signals:sdk-stubs. Use php artisan help <command> for their options.
Admin: /plugins (plugins.index), gated by plugins.manage.
Package anatomy
Canonical layout for an illustrative package acme/ledger-sync (detail: Folder structure):
plugins/acme/ledger-sync/
├── composer.json # PSR-4 + extra.signals.plugin
├── signals.yaml # validated manifest
├── database/migrations/ # plugin_*-prefixed tables only
└── src/
├── LedgerSyncPlugin.php # extends PluginBase
├── LedgerClient.php
├── LedgerContactPusher.php
├── LedgerInvoicePusher.php
└── Models/LedgerSyncLog.php
This tree is illustrative — the package is not shipped with Signals. For a real package you can read in this repository, see the acme-example package in the repository's plugin test fixtures.
The current extension surface is registry-based. A registry is a framework service that records definitions, drivers, validators, resolvers, or metadata for one domain area. Some of these registries already have core consumers and tests; some are empty seams designed for extension.
Local discovery supports both plugins/{name}/ and vendor-nested plugins/{vendor}/{name}/. Optional lifecycle hooks on PluginBase: install(), enable(), disable(), uninstall(), onUpdate(), boot().
Known limitations
| Limitation | Detail |
|---|---|
| Hot-boot | Enable/disable does not register hooks/slots until the next application boot. |
| Settings dual path | Manifest settings read through PluginContext vs registrar->setting(SettingsDefinition) — see Settings. |
| Query builder | Allowlisted, paginated PluginContext::list() is available; arbitrary joins and query expressions are deferred. Listing UI is covered by DataTable SDK — see Coming soon. |
| Local discovery depth | One vendor nesting level under plugins/ (plugins/{vendor}/{name}). |
| Operation allowlist | Only registry-mapped actions; Gate still applies inside the action. |
| Decorator call sites | Registration is supported but core never invokes Decorator hooks. Filter (assignment.query) and Validator (assignment.creating) call sites are available — see Hooks. |
Registry contract reference
Each EXPOSE-v1 registry seam has a dedicated contract page describing identity, accepted input, collision rules, ordering, and shipped core registrations — authoritative for registry behaviour:
These EXPOSE-v1 registry contract pages are implemented and routable today (the Contracts group under Framework internals in the docs sidebar is the authoritative list):
| Area | Contract page | Current purpose |
|---|---|---|
| API abilities | Ability Registry | API token ability discovery metadata |
| Permissions | Permission Registry | Administrative permission metadata and grouping |
| Settings | Settings Registry | Settings groups, defaults, validation rules, and type metadata |
| Webhooks | Webhook Event Registry | Outbound webhook event discovery metadata and metering weights |
| Domain events | Event Registry | Canonical domain-event catalogue and consumer visibility flags |
| Shortage costing | Cost Apportionment Registry | Virtual-stock cost allocation strategies |
| Deal pricing | Agreed Price Validator Registry | Validators before proportional agreed-price distribution |
| Notifications | Delivery Tracking Resolver Registry | Inbound delivery-tracking payload resolvers |
| Availability | Demand Source Registry | Availability demand definitions and resolvers |
| Discounts | Discount Criteria Predicate Registry | Discount criteria predicates |
| Discounts | Discount Source Registry | Runtime discount sources for rental totals |
| Documents | Document Resolver Registry | Document data resolvers and resolve extenders |
| Documents | Document Type Registry | Document type metadata, aliases, and source-model mapping |
| Documents | Plugin Document Template Seeder Registry | Warehouse-scoped document-template seeder callbacks |
| Plugin SDK | Plugin Hook Registry | Plugin hook handler registrations by name, type, and priority |
| Plugin SDK | Plugin Operation Registry | Operation name → core action class mapping |
| Plugin SDK | Plugin Tool Registry | Plugin MCP/CLI tool definitions (PluginRegistrar::tool) |
| Plugin SDK | Plugin Data Table Registry | Plugin listing-table definitions (PluginRegistrar::datatable) |
| Documents | PDF Driver Manager | Document PDF driver registration and resolution |
| Notifications | Channel Provider Registry | Notification delivery drivers |
| Notifications | Merge Field Filter Registry | Merge-field rendering filters |
| Pricing | Rate Engine Registry | Calculation strategies and rate modifiers |
| Rental workflow | Plugin Validator Registry | Transition-rule validators in the rental guard pipeline |
| Plugin SDK | Slot Registry | Plugin UI slot injections with priority and permission gating |
| Shortages | Shortage Resolver Registry | Shortage resolver definitions and implementations |
| Notifications | Recipient Resolver Registry | Notification recipient-rule resolvers |
These links use the public docs routes. The nested Markdown source path under docs/development/registries is an implementation detail.
Uploaded archive trust
Self-hosted archive uploads require the owner or an administrator with plugins.install. Unsigned ZIP archives are accepted on self-hosted installations. Enabling, disabling and configuring plugins requires the owner or an administrator with plugins.manage; Operations Manager does not receive either permission.
Signals Cloud refuses ZIP uploads at the upload action boundary. Cloud registry releases and indexes retain their trusted publisher signature verification.
RFID reader cycles
RfidBatchProcessor::process() accepts an optional batchRef after the actor. Supply a stable, reader-specific cycle reference and reuse it when retrying that cycle; each tag receives a deterministic session-local client_ref. A distinct cycle must use a new reference. Omitting batchRef starts a new cycle, preserving existing reader behavior. Each batch holds the session lock, checks authorization and open status, and commits all reads together. Failed batches leave no partial scan records or scan broadcasts.
What's new in 2.1
- Guarded finance and vehicle reads, bounded invoice lines/taxes, and opt-in version 2 event envelopes.
- Connections with encrypted configuration, OAuth and organisation selection; audited external payments with durable idempotency.
- Integration identities with explicit grants and immediate revocation.
- Core-rendered actions and forms, typed slot contexts, and maps with section polling.
- A sandbox app workflow and helpers for connections, principals, events, actions and refreshed sections.
Existing version 1 event payloads and array slot callbacks retain their behaviour. See Upgrading to 2.1 before adopting the new contracts.