Sdk Laravel Laravel Package

Getting Started

This release adds an opt-in contract, ExternalDatabaseWriterNetworkAccess, for managing a writer's allowed public IPv4 addresses. Nothing changes for existing writer provisioning, so an upgrade to 0.9.1 is safe to ship on its own — the new surface is only reachable once you resolve the contract.

Before writing any code, confirm the two prerequisites called out in the release:

1. The paired Core implementation is installed and at a compatible version.
2. The isolated-runtime implementation is deployed. The contract is explicitly documented as requiring both; resolving it without them will fail at call time rather than at install time.

Then check how the package binds the contract. In a typical Laravel integration you'll either be auto-binding a concrete class or publishing config that names one, so verify with:

php artisan about          # confirm package + versions
php artisan config:show external-database-writer   # or whatever the package namespace is

If nothing is bound, expect the container to throw on resolution — that's your signal that the optional feature isn't wired up yet, not a bug.

The first useful use case is CI/staging allowlisting: a deploy job reads the current allowed IPv4 list, appends the runner's egress IP, and writes it back with the revision it just read. The second is the inverse — clearing the list to revoke access when an environment is torn down.

Implementation Patterns

Read-modify-write with the revision. Every update is conditional on the revision returned by your last read. The canonical shape is:

$current = $writers->networkAccess($writerId)->read();

$result = $writers->networkAccess($writerId)->replace(
    ips: [...$current->allowedIpv4(), $newIp],
    revision: $current->revision(),
);

Treat the revision as opaque — store it, pass it back, never compute or increment it yourself. If you cache the allowed list anywhere (a config table, a Redis key), cache the revision alongside it or you'll be writing stale.

Model the saved/applied split explicitly. Responses distinguish saved policy from applied policy. These are not the same thing and the gap is where support tickets come from. Persist both states in your own schema if you surface network settings in a UI:

$result->savedPolicy();   // accepted and stored
$result->appliedPolicy(); // actually in force on the writer

A write that returns successfully but shows an unapplied policy means the request landed and the runtime hasn't reconciled it yet. Don't retry the write — that just burns revisions. Poll the read side.

Revocation is an empty list. There's no revoke() method; you replace with []. Wrap this so nobody does it accidentally:

public function revokeAll(int $writerId, string $revision): mixed
{
    return $this->writers->networkAccess($writerId)->replace(ips: [], revision: $revision);
}

Keep that behind an explicit, audited action rather than exposing "save the form" with an empty textarea.

Integration tip — provisioning pipeline. Run network-access changes as their own queued job after writer provisioning completes, not inline in the same transaction. The write is revision-checked against external state, so holding a DB transaction across it invites lock contention and pointless retries. Job middleware with release() on revision conflict works well here.

Integration tip — multiple writers. With many writers, fan out with Bus::batch() so a single conflicting writer doesn't stall the rest, then inspect failures per writer ID.

Gotchas and Tips

The browser IP is not the database client's egress IP. This is the single most likely source of "I allowlisted myself and it still fails." A developer loading your admin page from a laptop allowlists the laptop's public IP; the app server connecting to the database egresses from a completely different address. Always resolve the client IP server-side from the process that will actually open the connection, never from $request->ip() in the UI. If you can't determine egress reliably, surface it as a user-entered field with a warning rather than guessing.

Display application status before connection details. The release notes are direct about this: show network application status first, connection details second. Rendering a hostname and port next to a policy that hasn't applied yet reads as "this should work" when it won't. Gate the connection panel on applied — not saved — policy.

Empty list is destructive and easy to hit accidentally. A form submitted with no checkboxes sends [], which revokes all access and will drop live connections on the next reconciliation. Validate non-empty at the request layer for anything other than an explicit revoke route.

Revision conflicts need bounded retries. Re-read and retry, but cap it (two or three attempts) and then fail loudly. Unbounded read-modify-write loops against a shared contract can thrash if two automations are racing.

IPv4 only. Don't pass IPv6 addresses or CIDR blocks; the contract is scoped to public IPv4 addresses. Validate and normalize input (filter_var(..., FILTER_VALIDATE_IP, FILTER_FLAG_IPV4)) before it reaches the writer, and reject private ranges early with a clear message rather than letting the API do it.

Debugging. When a write is rejected, log the revision you sent alongside the revision the read returned — mismatches are almost always a stale cached value or a concurrent job. When a write is accepted but access still fails, compare saved vs applied and check the actual egress IP from inside the container (curl ifconfig.me from the app host, not from your machine).

Extension points. The contract is optional and interface-based, so you can decorate it — a logging decorator around replace() that records writer ID, revision, before/after IP sets, and the saved/applied outcome gives you an audit trail without touching the implementation. Bind the decorator in a service provider and leave the underlying binding intact.

Version coupling. Because this depends on paired Core and isolated-runtime implementations, pin all three to compatible versions in composer.json and roll them together. A 0.9.1 SDK against an older runtime is the most plausible "it resolves but behaves oddly" scenario.