SIGNALS Docs
Exit Reader View
100%
Theme

Plugin sandbox

Build and test a plugin in a local framework checkout with an isolated test database.

Prepare the framework

Use a development checkout of the framework release whose SDK satisfies your plugin's sdk constraint. The framework tag is its application release version, not necessarily the SDK version. Substitute your framework repository and that release tag:

git clone <framework-repository> signals-sandbox
cd signals-sandbox
git checkout <matching-release-tag>
composer install
npm ci
npm run build
cp .env.example .env
php artisan key:generate --no-interaction

Keep this checkout's .env local. Before the wiring check, set DB_CONNECTION=sqlite and DB_DATABASE to the absolute path of a new sandbox-only SQLite file. Create that file and run php artisan migrate --no-interaction against it. Never reuse a development or production database. Do not cache configuration: the package runner refuses cached configuration and production environments.

Tests use the framework's phpunit.xml environment. PluginTestRunner explicitly pins SQLite :memory: in its child process; PluginTestCase refreshes that isolated database. Package migrations must support SQLite. No separate runtime test-kit package is required; generated SDK stubs only provide editor and static-analysis signatures.

Add and check the package

Place the package at plugins/{vendor}/{name}/, including its signals.yaml, Composer PSR-4 metadata, source and tests/. Copy it, use a submodule, or symlink it. Discovery resolves paths with realpath, so a symlink targets the real package directory. For example:

mkdir -p plugins/acme
ln -s /absolute/path/to/ledger-connector plugins/acme/ledger-connector
php artisan signals:plugin check acme/ledger-connector --wire --json
php artisan signals:plugin test acme/ledger-connector --compact

Require valid: true and wire.ok: true in the check result. The wiring check calls registration in a discarded transaction and restored runtime checkpoint; package tests exercise boot and behaviour. The runner starts Pest on only the package's tests/, with the framework bootstrap and --no-tia. Each test file opts into uses(PluginTestCase::class); see Testing plugins for helpers, HTTP fakes and negative authorization cases.

Optional manual run

Complete the ordinary first-run setup in this disposable sandbox and create an administrator. The installer uses PostgreSQL: give it a new sandbox-only database, never a shared development database. Use a persistent sandbox cache so capability review survives between CLI invocations; array cannot retain the reviewed plan. For example, set this in the sandbox .env:

CACHE_STORE=database

Infrastructure installation caches configuration, so clear it after setup before returning to plugin checks or tests:

php artisan config:clear --no-interaction

Review the capability plan printed by the install command, then repeat with its exact hash. Finish installing one package before reviewing the next: changes to installed dependencies invalidate plans reviewed before them.

php artisan signals:plugin install acme/ledger-connector
php artisan signals:plugin install acme/ledger-connector --accept-capabilities=<reviewed-plan-hash>
php artisan signals:plugin enable acme/ledger-connector
php artisan signals:plugin principal acme/ledger-connector --grant --acting-user=1
php artisan queue:work --queue=default

Use the real administrator's ID instead of 1. Grant an integration identity only when the manifest declares one and after reviewing its permissions and warehouse scope. The host UI provides connection configuration, OAuth consent and action controls. A queue worker consumes the default queue for this sandbox; it must never point at a shared queue backend.

CI recipe

The following generic pipeline describes the required steps. Adapt the checkout and command keys to your CI, preserving the framework working directory and isolated test environment. Set FRAMEWORK_REPOSITORY, FRAMEWORK_TAG, PLUGIN_REPOSITORY and PLUGIN_REF to reviewed inputs.

steps:
  - name: Checkout framework
    run: |
      git clone --branch "$FRAMEWORK_TAG" "$FRAMEWORK_REPOSITORY" signals-sandbox
  - name: Checkout plugin
    run: |
      mkdir -p signals-sandbox/plugins/acme
      git clone --branch "$PLUGIN_REF" "$PLUGIN_REPOSITORY" signals-sandbox/plugins/acme/ledger-connector
  - name: Build sandbox
    working-directory: signals-sandbox
    run: |
      composer install --no-interaction
      npm ci
      npm run build
      cp .env.example .env
      php artisan key:generate --no-interaction
  - name: Check and test package
    working-directory: signals-sandbox
    run: |
      DB_CONNECTION=sqlite DB_DATABASE=:memory: CACHE_STORE=array php artisan signals:plugin check acme/ledger-connector --wire --json
      php artisan signals:plugin test acme/ledger-connector --compact

What the sandbox proves

Proves through assertions Does not prove
Manifest validity and registration wiring Real remote API behaviour or credentials
Permission refusals and guarded data projections Production tenancy and operator grant choices
HTTP allowlist enforcement with Http::fake() Production DNS, network reachability or remote rate limits
Connection, typed slot, event, action and refresh contracts Production queue topology or scheduling deployment

Use failure-path assertions as well as successful examples. Run remote-service acceptance checks separately with explicitly provisioned test credentials.