SIGNALS Docs

Plugin runtime

Context access, dependency injection, logging, cache keys and configuration.

Obtain a package context

Hook handlers and listen() listeners receive PluginContext first. Other registrar callbacks opt in by typing their first parameter as App\Sdk\PluginContext; core then adds the context before the usual arguments. This includes slot data, pages, palette commands, registerFilter, document-template seeders and resolver extensions, flightcase listeners, and column/datatable callbacks. Existing untyped callbacks keep their argument order.

use App\Sdk\PluginContext;
use App\Sdk\Slots\SlotComponentType;

$registrar->slot('dashboard.widgets', SlotComponentType::View, 'signals.stat-card',
    function (PluginContext $context, array $slotContext): array {
        return ['label' => 'Review queue', 'value' => $context->setting('queue_label', 'Ready')];
    });

In a PluginBase subclass, call $this->context() during register(), boot(), install(), enable(), disable(), uninstall() or onUpdate(). Outside a callback, PluginContext::forPackage('acme/review-test') loads the installed plugin's stored manifest; it throws for a missing plugin and checks the active package execution scope. It does not establish a tenant or sign in a user.

Context methods

Method Parameters Result
read string $entity, int $id Array of declared readable fields
list string $entity, array $filters = [], array $options = [] Array with data and next_cursor
dispatch PluginJob $job Void; queue a job for this package
update string $entity, int $id, array $attributes Boolean
operation string $action, mixed ...$args Core action result
setting string $key, mixed $default = null Decrypted, type-cast setting
connection string $key, ?int $connectionId = null A scoped PluginConnection
connections string $key The available connection handles for that declaration
hasIntegrationPrincipal None Whether a current integration identity grant exists
asIntegrationPrincipal callable $callback Callback result under the consented identity; prior authentication is restored
http None PluginHttpClient with declared host access
storage None PluginStorage scoped to the package
recent array $entry Void; label, URL and optional icon/type; requires a signed-in user
notify string $key, User|iterable $users, array $payload Void; declared notification type
emit string $name, array $payload = [] Void; declared event
log string $message, array $context = [], string $level = 'info' Void
logger None Psr\Log\LoggerInterface

Jobs receive their context in protected function run(PluginContext $context): void on a PluginJob subclass. Dispatch through the context to preserve package identity; see Jobs and schedules.

List declared data

Declare read and list, readable fields, and every filter you intend to use:

data_access:
  - entity: accounts
    operations: [read, list]
    read_fields: [id, name, is_active]
    filters: [is_active]
$page = $context->list('accounts', ['is_active' => ['eq' => true]], ['limit' => 25]);
$rows = $page['data'];
$nextCursor = $page['next_cursor'];

list() returns array{data: list<array<string, mixed>>, next_cursor: string|null}. Use next_cursor as the next call's cursor option with the same filters and ordering. Options are sort (default id), direction (asc or desc, default asc), limit (positive integer, default 25, capped at 100) and cursor. Cursors are signed and bound to package, entity, filters, ordering, user and tenant. No raw SQL, joins or arbitrary query-builder callbacks are accepted.

Data access, non-empty filter declarations and operation declarations participate in capability consent. Review and accept a new plan when expanding them; the test harness grants the selected fixture manifest through the real install flow. A filter must be declared in data_access[].filters and allowed by the entity map. Each value is an operator map: eq and in are available on allowed fields; text fields such as name also allow contains, and numeric identifiers/dates allow gte and lte. in accepts at most 100 scalar values. Values must match the field's type. Sorting is also allowlisted; a non-ID sort field must be readable. Filtering or sorting on a hidden account field is refused.

User visibility and auditing

Plugins see account fields exactly as the acting user does, further limited by the manifest's declared fields. Entity read permission is required; account identity, contact PII, credit and commercial fields need their corresponding permissions and are omitted otherwise. Privacy-restricted or purge-pending accounts, and related rentals and invoices, are hidden unless the user has accounts.privacy.case. Privacy filtering occurs before pagination. Existing warehouse scopes remain in effect.

Without a signed-in user, reads and lists are tenant-wide with no user warehouse filter, but restricted account fields and privacy-restricted records remain hidden. A context does not sign in a user or create a service principal.

Each successful list() call writes one audit row, not one per record, with package provenance and actor: user or actor: system. Successful single reads are not audited. Each write has one audit row, including unchanged writes, and each successful operation adds a plugin.operation row; core action domain events may also be recorded. Denials are audited. Audit persistence errors do not fail reads/lists; write auditing fails closed.

Core operations

Declare operation names in manifest operations[]. The registered operations are activities.create, activities.complete, favourites.toggle, rentals.change_status, rentals.allocate_assets and documents.generate. Every operation requires a signed-in user; no-user calls are refused and audited. Core actions retain their authorization and validation.

The three newer operations each take one input array:

Operation Input and result
rentals.change_status rental_id, integer status, optional expected_version and idempotency_key; returns id and status
rentals.allocate_assets rental_id plus the allocation action's fields, including its idempotency_key; returns id
documents.generate Document generation fields plus optional idempotency_key; returns document_id

Document generation keys are scoped to the plugin; repeating a key reuses the document while still checking source authorization. Without a key, each call generates a document. See Data access for write allowlists and custom fields.

Constructors and handlers

Discovery constructs the entry class with PluginBase::__construct(PluginManifest $manifest, string $package). The constructor is not declared final, but discovery supplies exactly those two values: do not add container dependencies to that constructor. Use an invokable listener or tool action for constructor injection. String listener classes and tool action classes are container-resolved. Closures are not resolved by the container. Only a first parameter typed PluginContext is filled in; the caller supplies the remaining arguments.

A tool action can declare __invoke(PluginContext $context, array $args). Its context parameter must be typed to receive injection. The register() method on PluginBase retains the concrete App\Services\Plugins\PluginRegistrar parameter; a subclass may widen it to App\Sdk\Contracts\PluginRegistrar.

Logs and cache keys

$context->log('Review completed', ['record_id' => 42]);
$context->logger()->warning('Review deferred', ['reason' => 'No response']);

PluginLogger writes through the default log manager and adds the package as plugin. Its package identity cannot be overwritten by a supplied context key. Use troubleshooting to locate the configured destination.

Prefix cache keys with your package, such as acme/review-test:summary. The framework's CacheService::qualifyKey() applies its configured namespace and Cloud tenant prefix. The plain Laravel Cache facade does not call that method automatically: explicitly qualify a plugin key before using the facade in Cloud, or use a suitable CacheService method. CacheService is a framework service, not part of the stable plugin SDK. Never retain tenant data or a context in static properties under Octane.

Settings and translations

Read plugin configuration through setting() and declare it in settings[], including secrets; application config() is not a plugin settings API. The default passed to setting() does not declare a key or grant access to an undeclared setting.

Discovery does not register a plugin lang/ directory or merge strings into core language packs. Plain strings work. A plugin that supplies translation files must arrange Laravel translation namespace/path registration itself; there is no automatic plugin translation registrar method.

Facade deprecation

Signals::* is deprecated in favour of the corresponding PluginContext method. The facade remains for the 1.x line; removal is a 2.0 change. Use operation(), log() and the other context methods above so package identity travels with the call.