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
namematchingsignals.yamlpackage - Non-empty
extra.signals.pluginFQCN that extendsApp\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
- Open Extensions → Plugins (
/plugins; the original/admin/settings/pluginsURL redirects there). - Confirm
acme/hellois listed as enabled; expand for overview / permissions / slots / settings. - Open the dashboard. With a user that can
acme.hello.view, thedashboard.widgetsslot should render ansignals.stat-cardlabelled 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:
- Edit
signals.yamland/orHelloPlugin::register(). php artisan signals:plugin check acme/hello --wire- Reload the app process (required after enable/disable; usually enough after code edits in local PHP-FPM).
- 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 |