SIGNALS Docs
Exit Reader View
100%
Theme

Plugin jobs and schedules

Dispatch package jobs and register recurring work with tenant scope and overlap locks.

Dispatch a plugin job

Extend App\Sdk\Jobs\PluginJob and implement protected function run(PluginContext $context): void. The final handle() method restores package scope, checks eligibility and supplies the context. The inherited constructor accepts the package name and selects the default queue.

use App\Sdk\Jobs\PluginJob;
use App\Sdk\PluginContext;

class RefreshReviewSummary extends PluginJob
{
    protected function run(PluginContext $context): void
    {
        $context->log('Refreshing review summary');
    }
}

$context->dispatch(new RefreshReviewSummary($context->package));

Use $context->dispatch(PluginJob $job): void so the queue payload carries the dispatch package. A different package is refused. If you add a constructor for record identifiers, call parent::__construct($package). Keep durable identifiers in the job rather than serialising a request's context.

Before execution, core skips work for a disabled or missing plugin, missing package code, or a stale capability grant. A queued job is checked again when handled. Creating a PluginContext does not make a job eligible; dispatch and execution still verify the installed package and its current capability grant.

Declare and register a schedule

Declare each local slug in schedules[], with exactly one of cron or frequency. description is optional. Keys must be unique within the package. Schedules participate in capability consent: adding one requires approval of the new capability plan before queued work is eligible.

schedules:
  - key: refresh-summary
    frequency: hourly
    description: Refresh the review summary

Supported frequencies are everyMinute, everyFiveMinutes, everyFifteenMinutes, everyThirtyMinutes, hourly, daily and weekly. Alternatively, use a valid five-field cron expression, such as cron: '0 2 * * *'. The runner evaluates it in config('app.timezone').

Register the declared key during register() using either a callable that accepts PluginContext, or a PluginJob class:

use App\Sdk\PluginContext;

$registrar->schedule('refresh-summary', function (PluginContext $context): void {
    $context->log('Refreshing review summary');
});

For the job above, use $registrar->schedule('refresh-summary', RefreshReviewSummary::class) instead. Core constructs a scheduled job with the package name only, so that class must not require additional constructor arguments. schedule(string $key, callable|string $handler): self rejects undeclared keys.

Runner, locks and retries

The host scheduler invokes signals:plugins:run-schedules every minute. It queues due entries for enabled plugins; in Cloud, tenant fan-out supplies each tenant context and a shared tick timestamp. The command does no work in the central Cloud context. It accepts --at for an explicit tick. Package code should not register a second host scheduler entry for the same schedule.

Each run boots the current tenant's plugins and obtains a lock scoped to tenant, package and schedule key. The lock expires after 21,600 seconds (six hours). An overlapping run is skipped. For a callable, core releases the lock after the invocation, including failure. For a scheduled PluginJob class, ownership transfers to the queued job: the lock remains across queue releases and retries, and is released on success, terminal failure or an eligibility skip. The expiry also covers a worker that dies before releasing it.

Callable exceptions are recorded and isolated; the runner does not rethrow them for queue retries. A PluginJob::run() exception is recorded and rethrown, so Laravel's configured job/worker retry policy applies. The SDK sets no separate retry count or backoff. Make side effects idempotent. The overlap lock prevents concurrent runs, not every possible repeated execution.

Hooks, schedule callbacks and PluginJob executions share the package's consecutive-failure counter. Success clears it; failures reach the same plugins.hook_failure_threshold (default 10) and can disable the plugin. A scheduled job's successful dispatch is not counted as successful job execution.

Tenant and data access

Cloud queue propagation stamps work with signals_tenant and its database generation, establishes the tenant connection before plugin boot/deserialisation, and restores the central context afterwards. Package stamps prevent queued work from switching package identity. The SDK does not serialize the dispatching user's authentication. SDK 2.1 jobs can opt into a consented integration identity with protected bool $runsAsIntegrationPrincipal = true;. Schedules declare principal: true. Both recheck the grant at execution and restore authentication afterwards.

Without a user, read() and list() query the current tenant without a user warehouse filter. Account identity, contact PII, credit and commercial fields remain hidden; privacy-restricted and purge-pending accounts and their related rentals/invoices are excluded. With a user, entity permissions, account field permissions and warehouse scopes apply. Successful list() calls produce one audit row with actor: system or actor: user; successful single reads do not produce audit rows. Writes and operations have their own per-call audit records. operation() requires an acting user and refuses and audits calls without one. For background operations such as payments.record_external, use the consented integration principal: set the job flag or schedule declaration above, or wrap the call in $context->asIntegrationPrincipal(...). The principal supplies the actor and retains permission, field, warehouse and operation checks.

See Runtime for declared filters and operations, and Testing plugins for queue fakes and package-owned tests.