ApiSutra Laravel

Use ApiSutra SDKs through familiar Laravel tools: dependency injection, lazy collections, fakes, events, queue middleware, and Artisan.

The core handles HTTP, DTOs, authentication, retries, and concurrency. This package connects those capabilities to your application. Laravel 13.12+ · PHP 8.4+.

Reference

Install

Composer installs the core too; package discovery registers the integration. Default bindings work without publishing configuration or setting up a database, Redis, or workers. Your SDK supplies its client, API address, and credentials. Explicit application bindings retain priority.

Use your SDK through DI

With a Laravel-compatible SDK registered and configured, resolve its client or inject it into a controller or job. CatalogClient and GetProduct below represent your SDK classes:

ClientConfigFactory supplies application debug/environment defaults. Requests are also available through DI; transferring incoming HTTP input is an explicit RequestFactory operation. Setup and configuration →

Process paginated data lazily

For a paginated SDK request already bound to its client, and your application's $repository:

This is a LazyCollection over the core's sequential item stream. DTOs remain objects, pages load as needed, and a FAILED page throws instead of silently truncating the list. Collection behavior →

Import from an Artisan command

Use the registered client for a catalog synchronization. Here $requests is a lazy iterable of SDK requests; $onResult and $onError are application handlers receiving a result or exception plus the source request:

With the built-in transport, up to five requests run concurrently; handlers process results without retaining the full collection. The command waits for completion and can report $summary->successful and $summary->failed. This uses the core's existing pool consumption through Laravel DI, with the client's configured auth and execution policies.

Test the client your application uses

Add ApiSutra\Laravel\Testing\InteractsWithApiSutra to your base Laravel TestCase once. In a test where /products/42 uses the registered CatalogClient:

Missing mocks fail the test even if the application ignores the SDK result. Teardown restores the original transport. Pass ApiSutra::for($client) for a specific instance; class lookup requires a shared/scoped binding. Assertions count HTTP transport attempts, including retries, rather than business operations. Testing contract →

Release a throttled job

In an existing queued job using Laravel's Queueable trait, add this middleware method. Its handle() continues to use the SDK normally:

When local quota or an active server cooldown refuses admission, middleware interrupts the job and releases it with a delay. The whole job will repeat: earlier HTTP requests and application changes are not rolled back. Attach it only when those effects can safely repeat; delayed release requires a queue connection that schedules delayed jobs. Queue behavior and limits →

See which SDK operations are slow or failing

Enable apisutra.integration.observation.enabled in application configuration, or use automatic observation with active Telescope outside testing. Register a listener in your application provider's boot():

The log entry includes the operation, outcome, duration, HTTP attempt count, and reason/stage when available. Your listener can send these summaries to application metrics too. Capture uses a bounded buffer; events are delivered at HTTP, job, or command boundaries. By default, only root executions are observed. Payload, delivery limits and logging without a listener →

Capability map

Execution and lifecycle

With the built-in Guzzle transport, async requests and pools need no event-loop setup. Await results before a controller or job returns; sendAsync() does not schedule a background job. Queue middleware is optional and applies to repeatable jobs in applications already using Laravel queues.

Supported scenarios include ordinary HTTP requests, Artisan, and sequential queue jobs. Full Octane/Swoole support and automatic tenant switching are not promised; use the documented client lifecycle and boundaries.

Next steps

• Use an existing SDK in Laravel.
• Add Laravel support to your SDK.
• core capabilities.

MIT license.