Plugin SDK

Working Plugin SDK guide for Signals extensions, with current registry seams separated from future stable SDK guarantees.

Planned SDK / pre-release: This guide describes the direction of the Plugin SDK, not a stable plugin-author contract. Use the registry contract pages to understand current framework seams, but do not rely on transitional internals or planned API shapes until the stable SDK documentation is available.

Status#

Signals currently exposes a set of framework registries that core code and early plugin-facing seams can use. Their contract pages describe current behavior: identity, accepted input, lookup behavior, collision rules, ordering, and shipped core registrations.

The stable Plugin SDK has not landed. Treat the following as planned, not available compatibility guarantees:

• Composer package discovery for third-party plugins
• YAML plugin manifests
• plugin lifecycle phases such as discover, register, activate, boot, disable, or uninstall
• a stable App\Sdk namespace or facade for mediated data access
• manifest-declared routes, permissions, fields, widgets, hooks, or settings

Do not build a production plugin against this page alone. Use the linked registry pages to understand today's framework extension points, and wait for the stable SDK documentation before relying on a supported plugin-facing boundary.

How to use this page#

Use this handbook as a navigation layer:

1. Start with Current framework seams to understand what exists today.
2. Open the relevant registry contract before writing code against a seam.
3. Review the Table of contents for direct links into the planned lifecycle and deferred guidance sections.
4. Check Planned SDK guarantees before treating any plugin concept as stable.
5. Review Appendix: deferred seam guidance for areas that are intentionally not stable yet.

The registry pages are more authoritative for current behavior than this overview. They describe each registry's public methods, accepted registration shape, collision behavior, failure behavior, ordering, and current core catalogue where applicable.

Table of contents#

• Current framework seams
• Implemented registry contracts
• Planned lifecycle
• Planned SDK guarantees
• Planned architecture direction
• Appendix: deferred seam guidance

Current framework seams#

The current extension surface is registry-based. A registry is a framework service that stores 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.

Current framework seams are implementation facts, not SDK promises:

• A registry page documents the behavior of the current PHP service.
• A registry page may mention PluginRegistrar only as an existing integration fact where that is true.
• Current PluginRegistrar methods are transitional glue and are not documented here as a long-term compatibility API.
• Direct use of framework classes may need to change when the stable SDK boundary is introduced.

When a registry page documents replacement, append, duplicate-rejection, ordering, or lookup behavior, that behavior belongs to the current framework contract for that registry. It does not imply that the stable SDK will expose the same method names or require plugin authors to call those services directly.

Implemented registry contracts#

These 19 EXPOSE-v1 registry contract pages are implemented and routable today:

These links use the public docs routes. The nested Markdown source path under docs/development/registries is an implementation detail.

Planned SDK guarantees#

The stable SDK will define the supported plugin-author boundary. Until then, the following are design direction only:

The stable SDK should be documented as a plugin-facing contract when it exists. That future document can refer back to the registry contracts where those registries remain the underlying framework mechanism.

Planned lifecycle#

The target lifecycle direction is explicit framework-managed phases for discovering, registering, activating, booting, disabling, and uninstalling plugins. Those phase names describe the intended shape of the lifecycle, not callable hooks or ordering guarantees that plugin authors can depend on today.

Until the stable SDK exists, treat lifecycle language in this handbook as design direction only. This page does not define hook signatures, lifecycle callbacks, phase timing, retry behavior, failure recovery, or guarantees about which framework services are available during each phase.

Planned architecture direction#

The target distribution model is a Composer-installed plugin package. The stable SDK documentation will define the package discovery mechanism, package metadata expectations, install-time validation, and compatibility policy. Until that contract exists, a package being installable through Composer does not make it a supported Signals plugin.

The target manifest direction is YAML. The manifest is expected to become the static declaration layer for plugin identity and install-time compatibility checks, but this page does not define field names, nesting, defaults, validation rules, or supported declarations. The target registration architecture is a stable plugin-facing layer that may use registries underneath. The current PluginRegistrar service is transitional framework glue. Its methods are intentionally not documented here as a compatibility promise, and plugin authors should not treat the current method list as the future SDK surface.

The target mediated-access direction is a future App\Sdk\ boundary for plugin-safe queries, actions, and host services. Direct Eloquent access, direct service-container access, and direct registry calls are current framework implementation details unless a registry contract page says otherwise for that registry's present behavior.

An illustrative future package might contain a manifest file and a service provider-like registration entry point, but the stable SDK documentation will define the exact file names, hooks, routes, settings, HTTP-client guidance, facade/API shape, and reference plugin.

Appendix: deferred seam guidance#

This appendix is planned guidance, not a stable plugin-author contract. It names known extension seams so their future direction is visible, but the exact plugin-facing instructions, compatibility guarantees, declarations, lifecycle phases, and host APIs are not defined yet.

Import/export transforms#

Signals is expected to need plugin-visible import and export customization, but this page does not define how plugins declare transforms or when those transforms execute. The stable SDK will define the supported boundary for row mapping, file metadata, validation ordering, dry-run behavior, failure reporting, idempotency, and rollback semantics.

Until that work lands, existing import/export services should be treated as framework internals unless a dedicated contract page says otherwise. Do not infer manifest keys, hook names, queue behavior, or direct service calls from this appendix.

Scan contexts#

Scan contexts are a known extension area for workflows that collect identifiers from barcode, RFID, or similar capture flows. The current framework may contain services, contracts, or UI paths that describe those flows, but this appendix does not make them stable SDK entry points.

The stable SDK will define how a plugin can contribute scan workflows, supported devices, parser behavior, validation feedback, stock-location rules, and operator-facing UI. Until then, plugin-author guidance for scanner workflows, device integrations, and label-printer behavior is intentionally deferred.

Navigation seams#

Plugins are expected to need navigation placement eventually, but this page does not define stable slots, labels, icons, permission checks, route binding, cache invalidation, command-palette entries, or tenant/store scoping. Existing navigation registration should be read as current framework behavior only.

The stable SDK will define the supported navigation model and how it relates to routes, permissions, settings, and lifecycle. Until then, this appendix is only a pointer to planned SDK work, not instructions for shipping plugin navigation.

When a deferred seam overlaps a current registry page, rely on the registry page only for the current framework contract it documents. Future SDK appendices may expose those capabilities through different names, facades, lifecycle phases, or manifest declarations.

What this page does not define#

This guide is not a complete Plugin SDK reference. It does not define the manifest, lifecycle callbacks, package layout, routes, permissions, configuration, or data-access APIs.

The linked registry contract pages describe current framework seams. Stable SDK documentation will define the supported plugin contract.