SIGNALS Docs

Plugin storage and HTTP

PluginStorage confinement rules, PluginHttpClient host allowlist and redirect behaviour, testing with Http::fake / Storage::fake, and the ledger client example.

Use the package-bound PluginContext supplied to your handler for plugin operations. During framework-mediated plugin execution, a facade call targeting another package throws PluginPackageMismatchException with reason plugin_package_mismatch; core and admin calls outside a plugin scope retain their existing behaviour.

HTTP — PluginHttpClient

Obtain a client from the injected PluginContext $context (or $this->context() in a lifecycle method):

$client = $context->http();

Allowlist rules

  • Exact host match against manifest network[] (case-insensitive).
  • No subdomain wildcards — declare each concrete host.
  • Every send validates DNS addresses with WebhookUrlGuard and pins the cURL connection to a validated address. Private, loopback, link-local and reserved targets are refused unless the self-host administrator enables api.allow_private_webhook_targets.
  • Client uses withoutRedirecting() so a 3xx Location cannot escape the allowlist.
  • Timeouts: request 30s, connect 10s.
  • Blocked hosts throw PluginHttpException and never hit the transport.

Failure message shape:

Plugin [{$package}] is not allowed to request host [{$host}].

Manifest validation for network entries: Plugin manifest (network.wildcard rules).

Ledger API worked example

Manifest:

network:
  - api.example.com
  - identity.example.com

Usage pattern for an illustrative acme/ledger-sync package:

$response = $context->http()
    ->post('https://api.example.com/contacts', $body);

LedgerClient::forPlugin($plugin) builds on $plugin->http() (or PluginContext::http() inside hooks).

Storage — PluginStorage

$storage = $context->storage();

Confinement

Root path:

plugins/{vendor_package_snake}/

/ and - in the package name become _:

Package Root
acme/example plugins/acme_example/
acme/ledger-sync plugins/acme_ledger_sync/

Rejected paths: empty, null byte (\0), absolute (/ or C:\…), any .. segment, or any path that escapes the root after normalisation.

API

Method Role
put Write
get Read
exists Presence
delete Remove
files List under a relative prefix
path Resolve confined absolute path
confine Validate / normalise a relative path

Violations throw PluginStorageException.

path() is available only for local filesystem disks and throws PluginStorageException for remote storage such as S3.

Testing patterns

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Storage;

Http::preventStrayRequests();
Http::fake([
    'https://identity.example.com/connect/token' => Http::response([...], 200),
    'https://api.example.com/contacts' => Http::response([...], 200),
]);

Storage::fake(); // when asserting PluginStorage writes on the default disk

Use App\Sdk\Testing\PluginTestCase for a real package context. See Testing plugins and Examples.

Connection-scoped grants

A connection handle binds HTTP requests to its package and connection. Its declared extends_network URL fields add saved HTTPS hosts to the manifest allowlist only while that connection sends a request. Other connections and the ordinary context HTTP client do not inherit those hosts. Revoked connections and disabled plugins cannot send requests.