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
WebhookUrlGuardand pins the cURL connection to a validated address. Private, loopback, link-local and reserved targets are refused unless the self-host administrator enablesapi.allow_private_webhook_targets. - Client uses
withoutRedirecting()so a3xx Locationcannot escape the allowlist. - Timeouts: request
30s, connect10s. - Blocked hosts throw
PluginHttpExceptionand 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.