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.