SIGNALS Docs
Exit Reader View
100%
Theme

Reader View

Building a Signals plugin with an LLM

Self-contained instructions an agent can follow to scaffold, validate, and test a Signals Composer plugin against App\Sdk.

How to use this page

Copy everything under Agent prompt block into an agent session. Point the agent at a Signals checkout. Prefer reading the linked plugin guides when unsure.


Agent prompt block

You are building a Signals framework plugin. Follow these rules exactly.

### Context
- Plugins are Composer packages with package-root signals.yaml + composer.json.
- Entry class extends App\Sdk\PluginBase and implements register(PluginRegistrar $registrar): void.
- Public stability boundary is App\Sdk\* excluding @internal, plus SdkSurface::STABLE_CLASSES. Use PluginContext for core data. The complete stable-class table is on /docs/development/plugin-sdk. register() may type-hint App\Sdk\Contracts\PluginRegistrar; the concrete parameter remains supported in 1.x.
- Local discovery supports plugins/{name}/ and vendor-nested plugins/{vendor}/{name}/.
- UI: no plugin-shipped Blade views. Declare slots; register core component names via registrar->slot().
- Slot families: detail header actions, detail tabs, index actions, boards, notifications.panel.actions, dashboard.widgets and modals.global. See /docs/development/plugin-ui.
- Detail tab hosts: `account.detail.tabs`, `rental.detail.tabs`, `catalogue_item.detail.tabs`, `fleet_vehicle.detail.tabs`, `flightcase.detail.tabs`, `asset.detail.tabs`, `credit_note.detail.tabs`, `payment.detail.tabs`, `invoice.detail.tabs`, `purchase_order.detail.tabs`, `repair.detail.tabs`, `equipment_test.detail.tabs`, `rental_project.detail.tabs`.
- Rental tab grouping: rental.detail.tabs may set the optional registrar slot argument group, or return group/tab_group in its payload (payload wins). Allowed keys are plan, fulfil, finance, docs, more; absent/invalid values fall back to more. This grouping metadata applies only to rental.detail.tabs.
- Modals: declare slot modals.global (component signals.plugin-modal for the config-driven Flux shell, or Html). Open from any surface: $dispatch('modal-show', { name: '...' }).
- Pages: declare nav (one group: group, icon, items[{key,label,page,permission?,icon?}]) + pages[] ({key,title,description?,layout: console, sections[{type: stat-grid|table|html|datatable|form|actions|connections|map}]}). Wire registrar->navGroup(label, icon, items) — must match declaration exactly — and registrar->page(key, dataProvider) returning section data keyed by section index. Renders at /plugins/{vendor}/{name}/{page}.
- Palette: registrar->paletteCommands(fn (): array => [{key,label,url,icon?,group?,keywords?,permission?}]) — no manifest section; permission must be null or a declared permissions[] key. navItem(show_in_palette: true) also lands in the palette.
- Recents: $context->recent({label, url (must start with /), icon?, type?}) — plugin must be enabled; appears in the search palette's Recently viewed list (and the matching list page's Recently viewed menu, if it has one). No SDK cap: one entry per user, plugin and URL; the palette shows the eight newest.
- Notifications: declare notifications[] ({key (vendor-prefixed), label, group?, channels? ⊂ database|mail|broadcast or logical channels from this plugin's channel_drivers[], description?}); wire registrar->notification(key, definition); send $context->notify(key, users, {title (required), body?, url? (internal path), icon?}).
- Channel providers: declare channel_drivers[] ({key (vendor-prefixed), channel (slug, not database/mail/broadcast), label, config_fields?}); implement ChannelDriver; wire registrar->channelDriver(key, class). Tenant config lives on ChannelProvider rows. Guide: /docs/development/plugin-channel-providers. Example plugins are installed separately.
- Currency FX: core ships manual entry plus ECB and Open Exchange Rates feeds; plugins can register another ExchangeRateProvider via registrar->exchangeRateProvider('key', Provider::class) into ExchangeRateProviderRegistry. Self-hosted installations select the active provider in Integrations, while Signals Cloud uses config('currency.cloud_provider').
- Provided events: declare events[] ({name (vendor-prefixed), label?, webhook?, workflow?}); registrar->event(name, {plugin?, webhook?, workflow?, ...}) requires each requested webhook/workflow flag in the manifest; registrar->webhookEvent(name, workflow: true) also requires manifest workflow: true; the default is false. Workflow-visible names are discovered by WorkflowTriggerRegistry and ApprovalChainRegistry from EventRegistry on each call. Names must be dotted and vendor-prefixed, declared before registration, and cannot shadow core or already-registered names. Fire $context->emit(name, payload). Any plugin (including the declaring one) may hook the name — call event() before the hook() that subscribes to it.
- Tables: only plugin_* (snake_case). Migrations run through PluginMigrationGuard.
- 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 their declarations.
- Network: concrete hostnames only in network[] (no wildcards).
- Data: accounts, rentals, invoices, credit_notes, payments, purchase_orders, vehicles, catalogue_items, assets, activities, warehouses, users, custom_field_definitions. Use read_fields/write_fields or fields[], with operations read/list/write; declare filters[] for list(). Only accounts, rentals, invoices and catalogue_items support writes. delete grants nothing. See /docs/development/plugin-data-access for the complete readable-field, filter and operation tables.
- Decorator: registered but no core call sites yet; a Decorator hook never runs.
- Hooks: PluginContext is the first handler argument. Prefer HookType::Event. Event/Filter names must exist in EventRegistry (or register via registrar->event() first).
- PluginContext methods: read, list, update, operation, setting, http, storage, recent, notify, emit, log, logger and dispatch. Use PluginBase::context() in lifecycle methods and PluginContext::forPackage() in class-based extensions such as channel drivers and workflow handlers.
- Scaffold: php artisan signals:plugin create vendor/name; then check vendor/name --wire, install with capability consent, and enable.
- 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.
- Enable is next-boot effective (no hot-boot).
- Import/export registrar methods importableModel/exportableModel/importTransform/planTemplate are available and need no manifest declaration. Worked examples: /docs/development/plugin-import-export.

### Folder structure
plugins/{vendor}/{name}/
  composer.json   # name, autoload.psr-4, extra.signals.plugin = FQCN
  signals.yaml
  database/migrations/   # optional, plugin_* tables only
  src/{Name}Plugin.php
  src/... handlers/clients/models as needed

### Minimal composer.json shape
{
  "name": "vendor/name",
  "autoload": { "psr-4": { "Vendor\\Name\\": "src/" } },
  "extra": { "signals": { "plugin": "Vendor\\Name\\NamePlugin" } }
}

### Minimal signals.yaml identity
package, name, version (SemVer), signals_version (e.g. "^1.0")
Optional sections: icon, sdk, requires, conflicts, permissions, data_access, tables, hooks, slots, settings, network, operations, nav, pages, notifications, channel_drivers, events, tools, datatables, workflow_handlers, workflow_triggers, workflow_conditions, schedules, routes, connections, actions, integration_principal

### PluginBase skeleton
namespace Vendor\Name;
use App\Sdk\PluginBase;
use App\Sdk\Contracts\PluginRegistrar;
class NamePlugin extends PluginBase {
  public function register(PluginRegistrar $registrar): void { /* … */ }
  // optional: boot, install, enable, disable, uninstall, onUpdate
}

### Registrar surface

- routes(string $method, string $path, callable $handler)
- verifier(string $key, App\Contracts\Notifications\VerifiesInboundRequest $verifier)

- schedule(string $key, callable|string $handler)
- package()
- manifest()
- documentType(string $documentType, string $resolverType, string $modelType, string $label, string $description = '', string $permission = 'documents.create', ?string $category = null, array $aliases = [])
- documentResolver(App\Contracts\Documents\DocumentDataResolver $resolver)
- extendDocumentResolver(string $resolverType, callable $extender)
- pdfDriver(string $name, string $driverClass)
- paymentDriver(string $name, string $driverClass)
- seedDocumentTemplates(callable $seeder)
- channelDriver(string $key, string $driverClass)
- action(string $key, callable $handler)
- actionOptions(string $actionKey, string $field, ActionOptionsProvider $provider)
- actionSlot(string $slot, string $actionKey, int $priority = 50)
- connectionTester(string $key, callable $tester)
- recipientResolver(App\Contracts\Notifications\RecipientResolver $resolver)
- deliveryTrackingResolver(App\Contracts\Notifications\DeliveryTrackingResolver $resolver)
- registerFilter(string $name, callable $filter)
- importTransform(App\Contracts\Imports\Transform|App\Contracts\Imports\TransformContract $transform)
- importableModel(App\Contracts\Imports\ImportableModelContract $model)
- exportableModel(App\Contracts\Exports\ExportableModelContract $model)
- planTemplate(App\Services\Imports\Plans\ImportPlanTemplateDefinition|App\Contracts\Imports\PlanTemplateContract $template)
- navItem(App\Services\Navigation\NavigationItem|array $item)
- rateStrategy(App\Contracts\CalculationStrategy $strategy, string $semanticVersion = '1.0.0', array $supportedTransactionTypes = ['rental','sale','service'], string $failurePolicy = 'fail_closed')
- rateModifier(App\Contracts\RateModifier $modifier, string $semanticVersion = '1.0.0', array $supportedTransactionTypes = ['rental','sale','service'], array $compatibleStrategies = ['period','fixed','hybrid'], string $failurePolicy = 'fail_closed', ?array $supportedStrategies = null)
- demandSource(App\Services\DemandSourceDefinition $definition)
- shortageResolver(App\Services\Shortages\ShortageResolverDefinition $definition)
- costApportionment(App\Contracts\CostApportionmentStrategyContract $strategy)
- discountPredicate(App\Contracts\Pricing\DiscountCriteriaPredicate $predicate)
- discountSource(App\Contracts\Pricing\DiscountSource $source)
- agreedPriceValidator(App\Contracts\Pricing\AgreedPriceValidator $validator)
- rentalValidator(App\Guards\Rentals\Contracts\TransitionRule $validator)
- column(string $entityType, array $config)
- workflowHandler(string $identifier, string $handlerClass, array $declaration = [])
- taxResolver(string $key, string $resolverClass)
- exchangeRateProvider(string $key, string $providerClass)
- evidenceKind(string $key, int $weight, bool $primary, ?string $description = null)
- doctorCheck(string $diagnostic)
- permission(string $key, array $definition)
- ability(string $key, array $definition)
- setting(App\Settings\SettingsDefinition $definition)
- 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)
- event(string $name, array $visibility = [], ?string $description = null, ?array $subject = null, ?array $redaction = null, ?array $samplePayload = null, ?string $provider = null, ?int $contract_version = null)
- notification(string $key, array $definition)
- hook(string $name, App\Sdk\Hooks\HookType $type, callable $handler, int $priority = 50)
- slot(string $slot, App\Sdk\Slots\SlotComponentType $type, string $component, ?callable $data = null, int $priority = 50, ?string $permission = null, ?string $group = null, ?int $refreshSeconds = null)
- tool(string $name, string $actionClass, string $title = '', string $description = '', array $args = [], string $permission = '', bool $readOnly = false, bool $destructive = false, array $surfaces = ['mcp','cli'])
- navGroup(string $label, string $icon = '', array $items = [])
- paletteCommands(callable $provider)
- page(string $key, callable $dataProvider)
- datatable(string $key, array $definition)
- datatableSlot(string $slot, string $datatableKey, int $priority = 0, ?string $permission = null)
- listen(string $eventName, callable|string $listener, int $priority = 50)
- onFlightcaseBeforePack(callable $listener)
- onFlightcaseAfterPack(callable $listener)
- onFlightcaseBeforeSeal(callable $listener)
- onFlightcaseAfterSeal(callable $listener)
- onFlightcaseBeforeDissolve(callable $listener)
- onFlightcaseAfterDissolve(callable $listener)
- onFlightcaseBeforeDispatch(callable $listener)
- onFlightcaseAfterDispatch(callable $listener)
- onFlightcaseBeforeRepack(callable $listener)
- onFlightcaseAfterRepack(callable $listener)
- onFlightcaseBeforeTransfer(callable $listener)
- onFlightcaseAfterTransfer(callable $listener)

### Operations
Seeded operations: activities.create, activities.complete, favourites.toggle, rentals.change_status, rentals.allocate_assets, documents.generate, payments.record_external, `payments.refund_external`, `payments.reverse_external`, `credit_notes.allocate_external`, `purchase_orders.mark_billed_external`, `purchase_orders.unmark_billed_external`.

### Context runtime API
Use PluginContext::read/list/update/operation/setting/http/storage/recent/notify/emit/log/logger/dispatch.
Signals::* is deprecated in 1.x and scheduled for removal in 2.0. For class-based extensions, obtain context with PluginContext::forPackage('acme/example').
Only a first callable parameter typed PluginContext receives the context before the usual arguments. In PluginBase lifecycle methods use $this->context().
The context manifest comes from YAML for registered callables and PluginBase::context(), and from the database copy for tool actions; permission checks always use the database copy.

### Key grammar
- Composer package: vendor/name; permission and event names use the vendor prefix and dotted segments.
- Permission segments use lowercase letters, digits and underscores, not hyphens.
- Page/nav/schedule keys use lowercase slugs; tables begin plugin_ and use snake_case.
- Exact regexes and examples: /docs/development/plugin-keys.

### Step order
1) Run php artisan signals:plugin create vendor/name, then edit signals.yaml (only sections you will wire).
2) Write composer.json with matching package name + plugin FQCN.
3) Implement PluginBase subclass register().
4) Add plugin_* migrations if needed; declare tables[].
5) Add hooks/slots/settings/network/nav/pages/notifications/events as required; keep wiring ⊆ declaration. Register event() before any hook() on the same name.
6) Tests: use App\Sdk\Testing\PluginTestCase and the public manifest/hook/fixture helpers; Http::fake / Storage::fake / Notification::fake for I/O.
7) Run: php artisan signals:plugin check vendor/name --wire
8) install + enable; restart PHP process; verify admin Plugins page, slots, and /plugins/{vendor}/{name}/{page} pages.

### Hard rules
- plugin_ tables only; never migrate core tables.
- No plugin views; config-driven slots only.
- No Eloquent queries on core models; use PluginContext. Framework callbacks may supply models for typed extension contracts.
- list() supports declared filters and signed cursor pagination; arbitrary query builders are unavailable.
- Permissions must use {vendor}. prefix from Composer package name.
- Do not invent registrar methods that are not in App\Sdk\Contracts\PluginRegistrar.

### Verification commands
php artisan signals:plugin list
php artisan signals:plugin check {package} --wire
php artisan signals:plugin install {package}
php artisan signals:plugin install {package} --accept-capabilities=<plan-hash>
php artisan signals:plugin enable {package}
php artisan signals:plugin test {package} --compact
# No checkout? Validate the manifest over HTTP (public, 30 req/min per IP):
# POST {host}/docs/tools/manifest-validate with JSON {"yaml": "<signals.yaml contents>"}
# -> {valid, errors, issues, parse_error?}; invalid manifests return 200, never 500.
# YAML parse failures return 422; oversized input 413; rate limiting 429.

### Canonical docs (read when blocked)
/docs/development/plugin-sdk
/docs/development/plugin-upgrades
/docs/development/plugin-troubleshooting
/docs/development/plugin-testing
/docs/development/plugin-slot-components
/docs/development/plugin-runtime
/docs/development/plugin-packaging
/docs/development/plugin-notification-templates
/docs/development/plugin-keys
/docs/development/plugin-jobs-and-schedules
/docs/development/plugin-inbound-requests
/docs/development/plugin-hook-payloads
/docs/development/plugin-event-catalogue
/docs/development/plugin-data-tables
/docs/development/plugin-getting-started
/docs/development/plugin-folder-structure
/docs/development/plugin-manifest
/docs/development/plugin-hooks
/docs/development/plugin-events
/docs/development/plugin-ui
/docs/development/plugin-data-access
/docs/development/plugin-data-models
/docs/development/plugin-registries-and-resolvers
/docs/development/plugin-examples
/docs/development/plugin-coming-soon   # aspirational only

Human notes

  • Separately installed kitchen-sink example: vendor/signals/slots-demo/.
  • Separately installed HTTP + custom-fields example: vendor/signals/ledger-sync/.
  • Minimal fixture: the acme-example package in the repository's plugin test fixtures.
  • After enabling, hooks/slots register only on the next application boot.

Machine-readable specification (JSON Schema)

The repository includes an internal versioned JSON Schema for structural checks in development tooling. JSON Schema is useful for structural checks, but it cannot replace authoritative validation. Cross-field checks include the package-derived vendor prefix, entity field/filter allowlists and declaration references; registration also enforces wiring ⊆ declaration. php artisan signals:plugin check {package} runs the authoritative validator and reports failures using the same rule keys the schema documents.

Programmatic validation over HTTP

Every Signals instance also serves the authoritative validator as a public, unauthenticated JSON endpoint (the same engine behind the interactive Manifest validator & builder):

POST {host}/docs/tools/manifest-validate
Content-Type: application/json

{"yaml": "package: acme/hello\nname: Acme Hello\nversion: 1.0.0\nsignals_version: \"^1.0\"\n"}

Responses:

Case Status Body
Manifest valid 200 {"valid": true, "errors": {}, "issues": []}
Validation rules failed 200 {"valid": false, "errors": {"tables.prefix": "…"}, "issues": [{"rule": "tables.prefix", "path": "tables.0", "message": "…"}]}
YAML cannot parse 422 {"valid": false, "errors": {"manifest.parse": "…"}, "issues": [{"rule": "manifest.parse", "path": "manifest", "message": "…"}], "parse_error": "…"}
Missing/empty yaml field 422 {"message": "…"}
Input over 64 KB 413 {"message": "…"}
Rate limit exceeded 429 —

Error keys are the manifest reference rule keys. Limits: 30 requests/min per IP, 64 KB per manifest; input is never stored.

Invalid manifest shapes return validation issues with status 200, never a server error. errors keeps the first message per rule; issues contains every {rule, path, message}.