SIGNALS Docs

Plugin getting started

Build and enable a minimal local Signals plugin in about ten minutes — folder layout, composer.json, signals.yaml, PluginBase, and CLI lifecycle.

Prerequisites

  • A working Signals install of the current release (Composer deps, migrations, Vite not required for CLI checks)
  • PHP 8.4 or 8.5 CLI available as php
  • Permission to create directories under plugins/

You do not need to publish a Composer package. Local discovery scans plugins/{name}/ and vendor-nested plugins/{vendor}/{name}/ (see Plugin folder structure).

1. Scaffold the package

php artisan signals:plugin create acme/hello

The scaffold requires ^8.4 and creates the Composer metadata, manifest and entry class, then validates the manifest. The following sections explain the generated files for a small greeting widget.

2. composer.json

{
    "name": "acme/hello",
    "description": "A Signals plugin.",
    "type": "library",
    "license": "AGPL-3.0-only",
    "require": {
        "php": "^8.4"
    },
    "autoload": {
        "psr-4": {
            "Acme\\Hello\\": "src/"
        }
    },
    "extra": {
        "signals": {
            "plugin": "Acme\\Hello\\HelloPlugin"
        }
    }
}

Discovery requires:

  • Composer name matching signals.yaml package
  • Non-empty extra.signals.plugin FQCN that extends App\Sdk\PluginBase
  • Package-root signals.yaml

Local packages are loaded on demand by PluginClassLoader from the package’s autoload.psr-4 map — you do not need to require the package from the application composer.json.

3. Minimal signals.yaml

package: acme/hello
name: Acme Hello
version: 1.0.0
signals_version: "^1.0"

permissions:
  - acme.hello.view

hooks: []

slots:
  - slot: dashboard.widgets
    component: signals.stat-card
    priority: 90
    permission: acme.hello.view

settings:
  - key: greeting
    type: string
    label: Greeting
    default: Hello from Acme Hello
    rules:
      - nullable
      - string
      - "max:255"

network: []

Permissions must use the Composer vendor prefix (acme.). Full rules: Plugin manifest.

When registering permissions in PHP, you may pass optional capabilities tags (money, operations, crm, admin, reporting, destructive) so the role builder wizard can place them under the right high-level toggles. Tag destructive grants explicitly.

Check your manifest as you type with the Manifest validator & builder — it runs the same ManifestValidator the install flow uses, and can generate this whole file from a form.

4. Plugin entry class

plugins/acme/hello/src/HelloPlugin.php:

<?php

namespace Acme\Hello;

use App\Sdk\Contracts\PluginRegistrar;
use App\Sdk\PluginBase;
use App\Sdk\PluginContext;
use App\Sdk\Slots\SlotComponentType;

class HelloPlugin extends PluginBase
{
    public function register(PluginRegistrar $registrar): void
    {
        $registrar->permission('acme.hello.view', [
            'label' => 'View Acme Hello',
            'description' => 'See the Acme Hello dashboard widget.',
            'group' => 'Integrations',
        ]);

        $registrar->slot(
            'dashboard.widgets',
            SlotComponentType::View,
            'signals.stat-card',
            static function (PluginContext $context, array $slot): array {
                return [
                    'label' => 'Acme Hello',
                    'value' => (string) $context->setting('greeting', 'Hello'),
                    'color' => 'blue',
                ];
            },
            90,
            'acme.hello.view',
        );
    }
}

Optional lifecycle hooks on PluginBase: install(), enable(), disable(), uninstall(), onUpdate(), boot().

5. Validate, install, enable

For a published plugin, use Extensions → Plugins → Add Plugin and install it from the registry. Self-hosted installations can use verified or community releases; Signals Cloud offers only the exact verified release reviewed by Signals. See Plugin registry.

For a local development package:

php artisan signals:plugin list
php artisan signals:plugin check acme/hello --wire
php artisan signals:plugin install acme/hello
# Review the printed plan, then run:
php artisan signals:plugin install acme/hello --accept-capabilities=<plan-hash>
php artisan signals:plugin enable acme/hello

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.

check --wire validates the manifest and calls register() in a rolled-back transaction with runtime state restored; it does not call boot(). install creates the plugins row, runs guarded migrations (none in this minimal package), seeds permissions and settings defaults, then calls PluginBase::install(). enable sets status enabled and calls enable().

Enable takes effect on the next application boot. PluginLifecycleManager::enable() does not hot-register hooks or slots. Restart PHP-FPM / Octane workers (or the next Herd request cycle after a process recycle) before expecting the dashboard widget.

6. Verify in admin + dashboard

  1. Open Extensions → Plugins (/plugins; the original /admin/settings/plugins URL redirects there).
  2. Confirm acme/hello is listed as enabled; expand for overview / permissions / slots / settings.
  3. Open the dashboard. With a user that can acme.hello.view, the dashboard.widgets slot should render an signals.stat-card labelled Acme Hello.

Edit the greeting under the plugin’s generated settings form, save, reload the dashboard after the next boot if you also toggled enable state.

7. Iterate

Typical loop:

  1. Edit signals.yaml and/or HelloPlugin::register().
  2. php artisan signals:plugin check acme/hello --wire
  3. Reload the app process (required after enable/disable; usually enough after code edits in local PHP-FPM).
  4. Re-test the slot / settings.

When you add tables, declare them under tables: as plugin_* names and put migrations in database/migrations/ — the lifecycle guard rolls back any batch that creates a non-plugin_ table. See Plugin folder structure.

Next reading

Guide Why
Folder structure Canonical tree and Ledger layout
Plugin registry Registry tiers, Cloud rules, provenance, and CLI
Manifest reference Every YAML section and validation message — including nav, pages[], notifications[], events[]
UI slots & navigation Slot types, live slot names, modals, nav groups + pages, palette, recents, notifications
Plugin events Provided events, PluginContext::emit(), self-subscription
LLM / agent guide Copy-paste agent instructions
Examples Separately installed examples plus the core acme-example test fixture