SIGNALS Docs
Exit Reader View
100%
Theme

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

Existing version 1 event payloads and array slot callbacks retain their behaviour. See Upgrading to 2.1 before adopting the new contracts.