Download the PHP package laravel-enso/api without Composer

API

Description

API is Laravel Enso's reusable package for external service integrations and inbound API request logging.

It provides a small action-based client on top of Laravel's HTTP client, optional SOAP transport through PHP's SoapClient, reusable contracts for authentication, retries, query parameters, file uploads, form payloads, and timeouts. On top of that, it standardizes inbound and outbound API logging, admin notifications for failed calls, and small payload-building helpers used across Enso integrations.

Installation

This package comes pre-installed in Laravel Enso distributions that integrate external services or expose protected internal API endpoints.

For standalone package installation inside an Enso-based application:

The package auto-registers its service provider, loads its migrations, and registers:

• the api-action-logger middleware alias
• the core-api middleware group
• the enso.api configuration namespace

Run the migrations after installation:

If you need to inspect raw request and response traffic during integration work, enable the debug flag in your environment:

Features

• Wraps outbound integrations in Action classes that resolve and execute Endpoint definitions.
• Builds requests through Laravel's HTTP client with support for:
  • bearer-token authentication
  • basic authentication
  • custom headers
  • query parameters
  • form submissions
  • file attachments
  • custom timeouts
  • retry policies
• Supports SOAP integrations through SoapEndpoint, SoapApi, SoapResponse, and the optional Endpoints\Soap base class.
• Refreshes an expiring auth token once automatically when an authenticated endpoint receives 401 or 403 on the first try.
• Logs outbound calls in api_logs, including URL, route, HTTP method, status, attempt number, payload, direction, and duration.
• Logs inbound calls through the ApiLogger middleware and reports non-200 responses to administrators.
• Provides a read-only System > API Logs table, with filters for user, permission, method, direction, and creation datetime.
• Queues ApiCallError notifications to active Enso admins on the notifications queue using shared laravel-enso/mails layouts and package-owned previews.
• Provides Resource and Filter base classes for payload shaping and input validation.
• Includes a Throttle helper for debouncing repeated external API calls.
• Ships the api_logs migration and an Api\Models\Log model with Enso caching traits.

::: tip Tip If an endpoint implements UsesAuth and the first response is 401 or 403, Api::call() refreshes the token once through the token provider before continuing with the normal retry flow. :::

Usage

Outbound action

Define a small endpoint class that describes the request:

Wrap it in an Action and call handle():

SOAP action

SOAP integrations use the same Action orchestration and logging flow. Extend the optional SOAP endpoint base class when the operation can be represented by wsdl(), operation(), and arguments():

Then return the SOAP endpoint from an action:

SOAP responses are wrapped in SoapResponse. Failed SOAP calls return a failed response internally, are logged, trigger the normal notification flow, and then throw the original SoapFault from handle().

Inbound logging

Use the standalone middleware alias when you only want request logging:

Or use Enso's core-api middleware group when the route also needs active-state checks, permission checks, and localisation handling:

Resource and filter helpers

Use Resource when a payload needs nested resource resolution and mandatory attribute validation:

Use Filter when you want to reject unsupported keys before sending them to the remote service:

API

Core classes

• LaravelEnso\Api\Api Builds and executes the HTTP request, applies optional contracts, tracks attempt count, refreshes bearer tokens once when needed, and retries failed calls when the endpoint allows it.
• LaravelEnso\Api\SoapApi Builds and executes SOAP calls through PHP's SoapClient, applies SOAP headers when provided, tracks attempt count, and retries SoapFault failures when the endpoint allows it.
• LaravelEnso\Api\SoapResponse Wraps successful SOAP results and failed SoapFault instances behind the response methods used by Action.
• LaravelEnso\Api\Action Orchestrates one outbound call, measures duration, persists the outbound log entry, reports failures, and returns either an Illuminate\Http\Client\Response for HTTP endpoints or a SoapResponse for SOAP endpoints.
• LaravelEnso\Api\Endpoints\Soap Optional base class for SOAP endpoints. It maps SOAP calls onto the existing Endpoint contract by defaulting method() to Method::POST, url() to the WSDL, location, or operation, and body() to the SOAP arguments.

Contracts

Required contract:

• Endpoint Defines method(), url(), and body().

Optional contracts:

• Client Internal transport contract implemented by Api and SoapApi.
• UsesAuth Adds bearer token support through a token provider.
• UsesBasicAuth Adds HTTP basic authentication.
• CustomHeaders Adds arbitrary request headers.
• QueryParameters Appends parameters() to the request URL.
• Retry Enables retries through tries() and delay().
• Timeout Sets a custom HTTP timeout.
• AsForm Sends the payload as form data.
• AttachesFiles Attaches files to the pending request.
• SoapEndpoint Extends Endpoint and defines wsdl(), operation(), arguments(), and options() for SOAP calls.
• SoapHeaders Adds SOAP headers through SoapClient::__setSoapHeaders().
• Token Defines the token provider contract used by UsesAuth.

::: warning Note SOAP support is additive. Existing HTTP endpoints keep using the same Endpoint contract and Api client behavior. Applications only need the PHP SOAP extension when they actually use SoapEndpoint. :::

Middleware

• api-action-logger Alias for LaravelEnso\Api\Http\Middleware\ApiLogger
• core-api Middleware group registered by the service provider:
  • LaravelEnso\Core\Http\Middleware\VerifyActiveState
  • LaravelEnso\Api\Http\Middleware\ApiLogger
  • LaravelEnso\Permissions\Http\Middleware\VerifyRouteAccess
  • LaravelEnso\Localisation\Http\Middleware\SetLanguage

Log model and storage

LaravelEnso\Api\Models\Log

Stored attributes:

• user_id
• route
• url
• payload
• method
• status
• try
• direction
• duration
• created_at
• updated_at

Relationships and casts:

• user() Belongs to LaravelEnso\Users\Models\User
• payload Cast to array
• method Cast to LaravelEnso\Api\Enums\Method
• direction Cast to LaravelEnso\Api\Enums\Direction

Logging directions:

• Direction::Inbound
• Direction::Outbound

API Logs table

The package provides the System > API Logs table through:

• GET /api/system/apiLogs/initTable
• GET /api/system/apiLogs/tableData
• GET /api/system/apiLogs/exportExcel

Permissions:

• system.apiLogs.index
• system.apiLogs.initTable
• system.apiLogs.tableData
• system.apiLogs.exportExcel

The table defaults to api_logs.created_at desc, exposes created_at as a datetime column, displays resolved users and permissions, and supports filters for user, permission, method, direction, and creation datetime.

Upgrade notes

This release changes the public logging enum contract:

• replace LaravelEnso\Api\Enums\Calls with LaravelEnso\Api\Enums\Direction
• replace Calls::Inbound / Calls::Outbound with Direction::Inbound / Direction::Outbound
• replace LaravelEnso\Api\Enums\Methods with LaravelEnso\Api\Enums\Method
• replace Method::get, Method::post, Method::put, and Method::delete with Method::GET, Method::POST, Method::PUT, and Method::DELETE
• update endpoint signatures from method(): string to method(): Method
• update application code or reporting queries that reference api_logs.type to use api_logs.direction
• update frontend API log filters from apiLogMethods to apiLogMethod

After updating the package, run:

Resource, filter, and throttle helpers

• Resource::resolve() Resolves nested resources and validates mandatory attributes.
• Resource::collection() Maps a collection into resolved resource arrays.
• Resource::toJson() Serializes the resource payload.
• Filter::toArray() Rejects unsupported keys before returning the filter array.
• Throttle::__invoke() Debounces repeated calls by sleeping until the configured interval has elapsed.

::: warning Note Inbound logging reports any non-200 response through ApiCallError, while outbound actions report failed responses and thrown exceptions through the same notification pipeline.

The notification handler targets active Enso admins and queues the email on the notifications queue. :::

Depends On

Required Enso packages:

• laravel-enso/core ↗
• laravel-enso/enums ↗
• laravel-enso/helpers ↗
• laravel-enso/localisation ↗
• laravel-enso/menus ↗
• laravel-enso/mails
• laravel-enso/migrator ↗
• laravel-enso/permissions ↗
• laravel-enso/rememberable ↗
• laravel-enso/tables ↗
• laravel-enso/upgrade ↗
• laravel-enso/users ↗

Framework dependency:

• Laravel framework ↗

Contributions

are welcome. Pull requests are great, but issues are good too.

Thank you to all the people who already contributed to Enso!