Download the PHP package getaviato/laravel without Composer

Aviato for Laravel

Extend an Aviato agent with custom actions, computed fields, hooks, segments, search, charts and custom datasources written in your Laravel application. The agent calls your app over the Aviato plugin protocol (ConnectRPC JSON, requests signed with Standard Webhooks); your code reads and writes records through the agent's Data API, under the caller's permissions and audit trail.

Requires PHP 8.3+ and Laravel 12 or 13.

Install

The SDK connects your application to an existing Aviato agent. Public agent binaries are not yet available from the default download URL. Supply your own agent binary or use an already running agent; omit --no-download only when a working agent download URL has been configured.

Configure

The package registers POST /aviato/aviato.plugin.v1.PluginService/{method}, POST /aviato/aviato.plugin.v1.DatasourceService/{method} and GET /aviato/files/{ref} outside the web middleware group (no session, no CSRF). Every request must carry a valid signature less than five minutes old, or it is rejected with 401.

Define an action

Register your plugin from a service provider's boot method:

Handlers can also be invokable classes (->execute(RefundLastInvoice::class)), resolved from the container. Throw Aviato\Laravel\Exceptions\RpcException (for example RpcException::permissionDenied('…')) to answer with a specific error code.

Custom datasources

Data the agent cannot reach through a database driver (an internal API, a SaaS, a file) can be served by your code as custom collections, under the same roles, row scopes, masking and audit trail as database collections:

get (defaults to a lookup through list), create, update and delete are optional. For slow sources, ->replication() with a listChanges handler lets the agent keep a copy, refreshed on the collection's interval (->replication(intervalSeconds: 300)) and on demand with Aviato::refreshReplica('tickets', $dataUrl). See the custom datasources guide.

Relations

Relations declared on your Eloquent models (belongsTo, hasOne, hasMany) are sent to the agent as relation hints, discovered with Laravel's model inspector. Models in app/Models are used by default; list them in aviato.relations.models to choose. Check what is sent with:

Run the agent

It runs the downloaded binary with AVIATO_CONTROL_PLANE_URL, AVIATO_AGENT_TOKEN, AVIATO_DATABASE_URL (built from your default connection), AVIATO_PLUGIN_URL and AVIATO_PLUGIN_SECRET. The binary is downloaded from aviato.agent.download_url ({version}, {os}, {arch} and {ext} are replaced); set aviato.agent.checksum_url to verify its SHA-256.

Testing

Aviato::fake() calls your handlers without an agent, with a fake caller and an in-memory Data API:

It also offers resolveForm, computeField, runHooks, resolveSegment, search, writeField, computeChart and manifest, and for custom datasources listCustomRecords, getCustomRecord, createCustomRecord, updateCustomRecord, deleteCustomRecord, listChanges and customCollections.

Custom summaries and forms

Aviato::summary($collection, $document) registers a native record overview. Use Aviato\Laravel\UI::document, UI::node, and UI::bind to build the shared JSON format, or load a document also used by the TypeScript and Go SDKs. For an action, pass UI::form($document) as the second argument to ->form($jsonSchema, $uiSchema).

The custom UI guide covers metric strips, property rows, reusable components, local state, field presets, and action buttons. Rendering uses Aviato's native design system without customer scripts or iframes. The agent still enforces permissions, validation, approvals, and auditing.

Development

The protocol messages in generated/ come from packages/protocol/proto through buf generate (remote plugin buf.build/protocolbuffers/php) and are serialized with the google/protobuf runtime's JSON mapping. They are committed, so Composer users never need buf.

License

MIT. See LICENSE.

Ready-to-use provider widgets

Use the typed StripePlugin implementation of IntegrationPlugin to register read-only Stripe customer, subscription and invoice widgets with a local ID column or a belongsTo relation. Credentials live in the customer agent environment; SDK declarations contain only the environment variable name. The browser calls the customer agent directly, and provider data does not pass through Aviato infrastructure.

See the provider widget guide for registration examples and exact key permissions. Restricted key prefixes do not prove read-only permissions: the operator must configure Read/None permissions in Stripe and confirm readOnly; the adapter itself only sends GET requests.

Zendesk widgets

The typed integration also supports user profiles and individual tickets. Bind to a local ID column or one belongsTo relation. Install a customer agent with Zendesk support before using these APIs. These examples require core SDK 0.3.0 (and NestJS adapter 0.2.0 when used). SDK releases do not publish agent binaries.

Store the OAuth token on the customer agent, with users:read / tickets:read scopes. Before each read, the agent verifies actual scopes and rejects write-enabled tokens. Only the subdomain label and credential environment-variable name belong in SDK configuration. No provider credentials or responses pass through Aviato's control plane. See the Zendesk guide for all methods, permissions and release requirements.