SIGNALS Docs

Plugin folder structure

Canonical package tree for a separately installed Signals plugin — composer.json, signals.yaml, plugin_ migrations, and the src entry class.

Canonical tree

Every plugin is a Composer package with a package-root signals.yaml. Core includes no plugins. A separately installed local development package may live under plugins/; a Composer-installed package is vendor-nested:

vendor/signals/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

Recommended layout for a new package acme/widget:

plugins/acme/widget/
├── composer.json
├── signals.yaml
├── database/
│   └── migrations/
│       └── 2026_07_17_120000_create_plugin_acme_widget_log_table.php
├── src/
│   ├── Acme/
│   │   └── WidgetPlugin.php   # or flat WidgetPlugin.php — match PSR-4
│   ├── Handlers/              # optional hook handlers
│   └── Clients/               # optional HTTP clients
└── tests/                     # optional package tests (or cover from app tests/)

Discovery paths

The framework discovers packages from these paths; plugin code does not construct the internal discovery or migration services:

  • Composer inventory: base_path('vendor/composer/installed.json')
  • Local root: base_path('plugins')

Local scan (discoverLocal):

  1. Scan immediate children of plugins/.
  2. For each child directory, try to load a package (signals.yaml + composer.json with extra.signals.plugin).
  3. If the child is not itself a package, scan one level deeper (plugins/{vendor}/{name}/).

So both of these work:

  • plugins/hello-world/ (flat)
  • plugins/acme/hello/ (vendor-nested — preferred; matches Composer acme/hello)

Composer-installed plugins are discovered from installed.json when extra.signals.plugin is set and signals.yaml exists at the install path. Local packages with the same Composer name as an already-discovered Composer package are skipped.

File roles

Path Role
composer.json Package identity (name), PSR-4 autoload, extra.signals.plugin → entry FQCN
signals.yaml Static declaration validated by ManifestValidator before plugin code runs
database/migrations/ Optional. Run only through PluginMigrationGuard on install/update
src/*Plugin.php Subclass of App\Sdk\PluginBase; implements register(PluginRegistrar $registrar)
Handlers / clients Plain PHP classes invoked from hooks or helpers — no Blade views
Eloquent models Allowed for plugin_ tables only (e.g. LedgerSyncLog → plugin_ledger_sync_log)

Migrations — plugin_ tables only

Declared in the manifest:

tables:
  - plugin_ledger_sync_log

During install and update, the framework migration guard:

  1. Snapshot table names.
  2. Run pending migrations in the plugin’s database/migrations/.
  3. Diff: newly created tables must match ^plugin_[a-z][a-z0-9_]*$; core tables must not disappear.
  4. On violation → roll back the batch and throw PluginLifecycleException.

Never migrate core tables from a plugin. Extend core entities with custom fields and the guarded data facade — see Data access and Data models.

No plugin-shipped views

Plugins never ship Blade views under the package. UI is config-driven: declare a slot in the manifest, then register a core Blade/Livewire component name (or trusted HTML) via PluginRegistrar::slot(). See Plugin UI.

Autoloading

Composer-installed plugins use the application autoloader. Local packages are registered by the framework when it instantiates the plugin entry class — it reads the package autoload.psr-4 map. Keep the extra.signals.plugin class under that namespace prefix.

Reference and fixture

Package Path
Separately installed example vendor/signals/ledger-sync/
Minimal test fixture acme-example in the plugin test fixtures

Annotated tour: Plugin examples.