SIGNALS Docs

Plugin registries and resolvers

Full PluginRegistrar fluent surface grouped by domain — exact signatures, manifest gates, examples, and links to registry contract pages.

Scoped registrar

The framework supplies an App\Sdk\Contracts\PluginRegistrar to register(), scoped to the enabled package and its manifest. Plugins do not construct or scope the registrar themselves. package(): ?string and manifest(): ?PluginManifest expose that registration identity.

Wiring ⊆ declaration: permissions, settings, hooks, slots, nav, notifications, channel_drivers, events, datatables, tools, schedules.

page() also requires a declared pages[] key. Nav group/items and slot/component pairs must match the declaration. Ungated seams still enforce their own contract, key and collision checks.


Auth & permissions

Method Signature Manifest gate Contract
permission permission(string $key, array $definition): self key ∈ permissions[] Permission Registry
ability ability(string $key, array $definition): self no Ability Registry

The permission() definition requires three string fields: label, description, and group. description is required even when it repeats the label; omitting it fails registration. Optional fields are sub_group, layer, dependencies, and capabilities. Declaring a key in permissions[] does not supply these registration fields. Run signals:plugin check <package> --wire to check the registration as well as the manifest.

$registrar->permission('signals.ledger.sync', [
    'label' => 'Sync with Ledger',
    'description' => 'Push accounts and invoices to Ledger.',
    'group' => 'Integrations',
]);

Settings

Method Signature Manifest gate Contract
setting setting(SettingsDefinition $definition): self every defaults() key ∈ settings[].key Settings Registry

Prefer manifest settings read through PluginContext::setting() for plugin-private config — see Plugin settings.


Events & hooks

Method Signature Manifest gate Contract
webhookEvent webhookEvent(string $name, ?string $description = null, ?array $subject = null, ?array $redaction = null, ?array $samplePayload = null, ?string $provider = null, ?int $contract_version = null, bool $workflow = false): self name ∈ events[] with webhook: true Webhook Event Registry / Event Registry
event event(string $name, array $visibility = [], ?string $description = null, ?array $subject = null, ?array $redaction = null, ?array $samplePayload = null, ?string $provider = null, ?int $contract_version = null): self name ∈ events[]; webhook: true requires manifest webhook: true Event Registry
notification notification(string $key, array $definition): self key ∈ notifications[] Channel Provider Registry
hook hook(string $name, HookType $type, callable $handler, int $priority = 50): self name ∈ hooks[]; Event/Filter must exist in EventRegistry Plugin Hook Registry
$registrar->hook('account.updated', HookType::Event, $contactPusher, 50);

Guide: Plugin hooks, Plugin events.


Workflow extensions

Workflow extensions are manifest-driven and version-aware. A scoped plugin may register an executable action handler through the one workflow-specific registrar method:

Method Signature Manifest gate Contract
workflowHandler workflowHandler(string $identifier, string $handlerClass, array $declaration = []): self identifier is vendor-namespaced; a scoped manifest requires its complete workflow_handlers[] declaration WorkflowHandlerRegistry
$registrar->workflowHandler(
    'acme.dispatch.driver',
    Acme\Signals\Workflow\DispatchDriver::class,
    $manifestDeclaration,
);

WorkflowHandlerRegistry owns class, identifier, duplicate, version, and declaration checks. It resolves handlers from the container and keeps registration metadata for diagnostics and health checks. Plugin handlers cannot shadow core identifiers; removing a plugin removes its owned registrations.

WorkflowTriggerRegistry registers manifest-declared trigger extensions and matches them against the constrained WorkflowTriggerContext. Its catalogue and diagnostics expose the registered event definition without discovering arbitrary classes. WorkflowConditionRegistry evaluates manifest-declared references against sanitized, allowlisted context and rejects live queries or mutations. Their manifest sections are workflow_triggers[] and workflow_conditions[]; they do not have additional fluent registrar methods.

WorkflowPluginExtensionManager activates handler, trigger, and condition registrations atomically. A failed replacement restores the preceding manifest registrations; disable or removal removes the plugin-owned extensions and leaves persisted references unhealthy. Health states include available, incompatible, disabled, missing, upgrade_required, and invalid.

See Workflow extensions and the manifest reference.


UI slots & navigation

Method Signature Manifest gate Contract
slot slot(string $slot, SlotComponentType $type, string $component, ?callable $data = null, int $priority = 50, ?string $permission = null, ?string $group = null, ?int $refreshSeconds = null): self slot+component pair ∈ slots[] Slot Registry
navItem navItem(array|NavigationItem $item): self no NavigationService (no dedicated contract page)
navGroup navGroup(string $label, string $icon, array $items): self label/icon must match nav; every item must match a declared nav.items[] entry PluginNavRegistry (no dedicated contract page)
page page(string $key, callable $dataProvider): self requires a plugin-scoped registrar; key ∈ pages[] PluginNavRegistry (no dedicated contract page)
paletteCommands paletteCommands(callable $provider): self no manifest section; each command's permission must be null or ∈ permissions[] PluginPaletteRegistry (no dedicated contract page)
datatable datatable(string $key, array $definition): self key ∈ datatables[]; a declared permission binds the definition to that exact key, and a permission is mandatory either way Plugin Data Table Registry
datatableSlot datatableSlot(string $slot, string $datatableKey, int $priority = 0, ?string $permission = null): self the slot must be declared in slots[] with component components.data-table; the datatable must already be registered Slot Registry · Plugin Data Table Registry

| column | column(string $entityType, array $config): self | no manifest section; the column key must carry the vendor prefix | Plugin Column Registry |

$registrar->datatable('acme.fieldops.jobs', [
    'model' => Job::class,
    'permission' => 'acme.fieldops.view',
    'searchable' => ['reference', 'title'],
    'columns' => [['key' => 'reference', 'label' => 'Job', 'sortable' => true]],
]);

$registrar->datatableSlot('dashboard.widgets', 'acme.fieldops.jobs', priority: 80);

column() is the other half: instead of a whole plugin-owned table, it adds row-addressable presentation metadata for a core entity's list views. The column is merged into that entity's ColumnRegistry when it boots, so a listable column can be rendered and offered by the host's picker. Registration does not create or load data or augment host queries; sorting, filtering, and export remain host-supported behaviors rather than automatic guarantees. Keys are public (saved live filters save them), so a plugin-scoped registration must carry the vendor prefix — which is what keeps a plugin from shadowing a core column.

$registrar->column('rentals', [
    'key' => 'acme.rental_reference',
    'label' => 'Plugin Reference',
    'field' => 'reference',
    'listable' => true,
    'sortable' => false,
    'filterable' => false,
]);

datatable() is config only — it resolves into mount params for the one canonical components.data-table Livewire component every core listing page uses, so plugin tables inherit search, sorting, filtering, column toggles, live filters, and CSV export. Render it from a datatable page section or through datatableSlot().

Guide: Plugin UI, DataTable SDK.


Documents

None of these are manifest-gated.

Method Signature Contract
documentType documentType(string $documentType, string $resolverType, string $modelType, string $label, string $description = '', string $permission = 'documents.create', ?string $category = null, array $aliases = []): self Document Type Registry
documentResolver documentResolver(DocumentDataResolver $resolver): self Document Resolver Registry
extendDocumentResolver extendDocumentResolver(string $resolverType, callable $extender): self — @param callable(array<string, mixed>, Model): array<string, mixed> Document Resolver Registry
pdfDriver pdfDriver(string $name, string $driverClass): self — @param class-string<PdfDriver> PDF Driver Manager
seedDocumentTemplates seedDocumentTemplates(callable $seeder): self — @param callable(Warehouse): void Plugin Document Template Seeder Registry
paymentDriver paymentDriver(string $name, string $driverClass): self — @param class-string<PortalPaymentDriver> Portal Payment Driver Manager — hosted-checkout providers must implement verified receipt contract v1 for the Document Portal pay rail

Guide: Plugin documents.


Notifications

Method Signature Manifest gate Contract
channelDriver channelDriver(string $key, string $driverClass): self yes (channel_drivers[]) Channel Provider Registry · Plugin channel providers
recipientResolver recipientResolver(RecipientResolver $resolver): self no Recipient Resolver Registry
deliveryTrackingResolver deliveryTrackingResolver(DeliveryTrackingResolver $resolver): self no Delivery Tracking Resolver Registry
registerFilter registerFilter(string $name, callable $filter): self no Merge Field Filter Registry

Pricing & rates

Method Signature Manifest gate Contract
rateStrategy rateStrategy(CalculationStrategy $strategy): self no Rate Engine Registry
rateModifier rateModifier(RateModifier $modifier): self no Rate Engine Registry
discountPredicate discountPredicate(DiscountCriteriaPredicate $predicate): self no Discount Criteria Predicate Registry
discountSource discountSource(DiscountSource $source): self no Discount Source Registry
agreedPriceValidator agreedPriceValidator(AgreedPriceValidator $validator): self no Agreed Price Validator Registry

rateModifier also accepts semanticVersion, supportedTransactionTypes, supportedStrategies and failurePolicy. Pass supportedStrategies by name to select the rate strategies that accept the modifier. When non-null, it takes precedence over the fourth positional argument.

Availability & shortages

Method Signature Manifest gate Contract
demandSource demandSource(DemandSourceDefinition $definition): self no Demand Source Registry
shortageResolver shortageResolver(ShortageResolverDefinition $definition): self no Shortage Resolver Registry
costApportionment costApportionment(CostApportionmentStrategyContract $strategy): self no Cost Apportionment Registry

Rental guards

Method Signature Manifest gate Contract
rentalValidator rentalValidator(TransitionRule $validator): self no Plugin Validator Registry

Diagnostics

Method Signature Manifest gate Contract
doctorCheck doctorCheck(string $diagnostic): self no Laravel\Doctor\Diagnostic

Adds a check to php artisan doctor, reported alongside the core Signals and Laravel diagnostics. Use it for the things only your plugin can verify — an integration's credentials, a partner endpoint that answers, a webhook secret that is still valid.

$registrar->doctorCheck(AcmeIntegrationIsConfigured::class);

Scaffold a diagnostic with php artisan make:diagnostic. Registration records the class only; it is not instantiated until a diagnostic run selects it, so nothing runs during the plugin lifecycle. Passing a class that does not extend Diagnostic throws PluginRegistrarException.

See System Health for the command and the core diagnostics.


Flightcase lifecycle listeners

These register Laravel Event::listen handlers. Manifest gate: matching hook name must be declared in hooks[].

public function onFlightcaseBeforePack(callable $listener): self
public function onFlightcaseAfterPack(callable $listener): self
public function onFlightcaseBeforeSeal(callable $listener): self
public function onFlightcaseAfterSeal(callable $listener): self
public function onFlightcaseBeforeDissolve(callable $listener): self
public function onFlightcaseAfterDissolve(callable $listener): self
public function onFlightcaseBeforeDispatch(callable $listener): self
public function onFlightcaseAfterDispatch(callable $listener): self
public function onFlightcaseBeforeRepack(callable $listener): self
public function onFlightcaseAfterRepack(callable $listener): self
public function onFlightcaseBeforeTransfer(callable $listener): self
public function onFlightcaseAfterTransfer(callable $listener): self

Import / export

Shipped with the import/export engine merge — real signatures from PluginRegistrar:

Method Registry Contract
`importTransform(Transform TransformContract $transform)` TransformRegistry
importableModel(ImportableModelContract $model) ImportTargetRegistry plugin import targets (+ optional SupportsPolymorphicImport)
exportableModel(ExportableModelContract $model) PluginExportRegistry plugin export sources (extends PluginExportHandler)
`planTemplate(ImportPlanTemplateDefinition PlanTemplateContract $template)` ImportPlanTemplateRegistry

These four seams need no manifest declaration. Walkthrough: Plugin import/export.

Field-level importable / exportable flags already exist on FieldDefinition / SchemaRegistry — that is not the same as registrar import/export seams.


Gate exception messages (examples)

  • Plugin [{$package}] attempted to register undeclared permission [{$key}].
  • Plugin [{$package}] attempted to register undeclared setting [{$key}].
  • Plugin [{$package}] attempted to register undeclared hook [{$name}].
  • Plugin [{$package}] attempted to register undeclared slot [{$slot}] component [{$component}].
  • Plugin [{$package}] attempted to register unknown hook [{$name}] of type [{$type->value}]; name must exist in EventRegistry.

Schedules

$registrar->schedule(string $key, callable|string $handler): self binds a declared schedules[] key to a PluginContext-typed callable or a PluginJob class. See Jobs and schedules for queue, scope, overlap and failure behaviour.

Actions and connections

SDK 2.1 adds action(string $key, callable $handler), actionOptions(string $actionKey, string $field, ActionOptionsProvider $provider), actionSlot(string $slot, string $actionKey, int $priority = 50) and connectionTester(string $key, callable $tester). Each returns the registrar and checks its manifest declaration. Core renders and validates the forms; plugins provide handlers and option providers. See Actions and Connections.