Plugin examples

Annotated tours of plugins/signals/xero-sync, signals/slots-demo, signals/slack-webhook, and the acme-example test fixture — repo-relative paths only.

Primary reference — signals/xero-sync#

Path: plugins/signals/xero-sync/

Full production-shaped reference that exercises discovery, manifest validation, guarded migrations, permissions, asymmetric data_access, Event hooks, HTTP allowlist, encrypted settings, a dashboard slot, and a plugin_* log table.

File tour#

What to copy from Xero#

1. Asymmetric fields — read contact/invoice attributes; write only custom_fields.xero_*_id.
2. Hook shape — __invoke(PluginContext $context, mixed ...$payload).
3. Settings — encrypted client_secret, enum sync_direction.
4. Slot — core signals.stat-card with permission signals.xero.view.
5. Network — api.xero.com, identity.xero.com only.

Install locally#

php artisan signals:plugin check signals/xero-sync
php artisan signals:plugin install signals/xero-sync
php artisan signals:plugin enable signals/xero-sync
# restart PHP process, then open /admin/settings/plugins and the dashboard

Kitchen-sink reference — signals/slots-demo#

Path: plugins/signals/slots-demo/

The canonical "every surface" example — one plugin that demonstrates every place a plugin can touch: one slot from every slot family, a global modal, a top-level nav group with two config-driven pages, a registered datatable, a palette provider, a recents push, a sendable notification, a provided (self-subscribed) event, a catalogued-event hook, a vendor-prefixed permission and three settings. Copy this when you want to see how each surface is wired in one place; copy Xero when you need HTTP + custom fields.

File tour#

Surfaces demonstrated#

Every surface is gated on signals.slotsdemo.view, and every registrar call matches a manifest declaration (wiring ⊆ declaration). Registration order matters in one place: event() must run before the hook() that subscribes to the same name, because Event-type hook names must already exist in EventRegistry.

Install locally#

php artisan signals:plugin check signals/slots-demo
php artisan signals:plugin install signals/slots-demo
php artisan signals:plugin enable signals/slots-demo
# restart PHP process, then open /plugins/signals/slots-demo/overview

Channel-provider reference — signals/slack-webhook#

Path: plugins/signals/slack-webhook/

Minimal Slack incoming webhook channel plugin — the canonical example for Plugin channel providers. Config is webhook URL + optional default channel name, stored on the tenant ChannelProvider row (not plugin settings).

File tour#

What to copy#

1. Manifest gate — channel_drivers[].key matches $registrar->channelDriver($key, …).
2. Logical channel — channel: slack may appear in notifications[].channels.
3. Tenant config — secrets on ChannelProvider, schema via configSchema().
4. Network allowlist — declare hooks.slack.com even when the driver uses the HTTP client from core delivery paths.
5. Tests — tests/Feature/Plugins/SlackWebhookPluginTest.php fakes Slack HTTP.

Install locally#

php artisan signals:plugin check signals/slack-webhook
php artisan signals:plugin install signals/slack-webhook
php artisan signals:plugin enable signals/slack-webhook
# restart PHP process, then open Admin → Settings → Notifications → Channel Providers

Minimal fixture — acme-example#

Path: tests/Fixtures/plugin-packages/acme-example/

Used by InstallsFixturePlugins and discovery tests. Not a production package, but a complete minimal shape:

Related fixtures for negative tests:

• tests/Fixtures/plugin-packages/acme-failing/ — failing hook behaviour
• tests/Fixtures/plugin-packages/acme-badtable/ — migration that creates a non-plugin_ table (guard rejection)

Test helpers#

$plugin = InstallsFixturePlugins::installAndEnable('acme/example');
// …
InstallsFixturePlugins::teardown($plugin);

Quickstart package#

For a greenfield local plugin under plugins/{vendor}/{name}/, follow Getting started. Prefer slots-demo when you want to see every UI / notification / event surface wired in one place; prefer Xero when you need HTTP + hooks + custom fields; prefer slack-webhook when you are building a notification channel provider; prefer acme-example when you need the smallest valid fixture for automated tests.