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.