Links
Comment on page
📡

Responses

Depending on how you sent your request (synchronous/asynchronous) you will either receive an instance of Response or a PromiseInterface.

Handling synchronous responses

By default, Saloon will return an instance of Saloon\Http\Response. This response class contains many helpful methods for interacting with your HTTP response. You can see a list of the available methods below.
<?php
​
$forge = new ForgeConnector('api-token');
$response = $forge->send(new GetServersRequest);
​
$body = $response->body();
$decodedBody = $response->json();
By default, Saloon will not throw an exception if a synchronous request fails. Refer to the handling failures section for handling errors.​

Available Methods

Method
Description
body
Returns the HTTP body as a string
stream
Returns the HTTP body as a stream
headers
Returns all the headers. You can interact with them just like you do with requests/connectors.
header
Returns a single header from the response.
status
Return the HTTP status messages
getPsrResponse
Returns a PSR-compatible response
getPendingRequest
Returns the PendingRequest created to send the request, containing everything sent like headers, body, and HTTP client config.
getRequest
Returns the original request class that was used to send the request.
json
Retrieves a JSON response body and json_decodes it into an array.
object
Retrieves a JSON response body and json_decodes it into an object.
xml
Retrieves the response body and creates a SimpleXmlElement.
collect
Retrieves a JSON response body and json_decodes it into a Laravel collection. Requires illuminate/collections to be installed.
dto
Converts the response into a data-transfer object. You must define your DTO first, click here to read more.​
successful
Returns true if the response status is between 200 and 300.
ok
Returns true if the response status is 200.
redirect
Returns true if the response status is between 300 and 400.
serverError
Returns true if the response status is >= 500.
clientError
Returns true if the response status is between 400 and 500.
failed
Determines if a request has failed. By default, it will return true if the response status is not 2xx.
onError
Allows you to define a callback if the response is considered "failed".
toException
Creates an exception if the response is considered "failed. Click here to read more about handling failures​
throw
Will throw an exception if the response is considered "failed".
isCached
Denotes if the response is cached. Only used when using the Saloon caching plugin.
isMocked
Denotes if the response has been mocked.
isSimulated
Denotes if the response was "simulated", like when a MockResponse was used.
getSimulatedResponsePayload
When the response is simulated, get the underlying SimulatedResponsePayload class.
getSenderException
Get the sender exception if a request failed.
getRawResponse
Get the raw response provided from the sender.
__toString
Returns the HTTP body as a string

Handling asynchronous responses

When using concurrent requests/pooling or sendAsync , Saloon will respond with a GuzzleHttp\Promise\PromiseInterface. The promise will contain a Response a class described above. When the request fails, Saloon will not use the then method but return an instance of RequestExceptionin the otherwise block.
<?php
​
use Saloon\Contracts\Response;
​
$forge = new ForgeConnector('api-token');
$promise = $forge->sendAsync(new GetServersRequest);
​
$promise
->then(function (Response $response) {
// Handle successful response
})
->otherwise(function (Exception $exception) {
// Handle failed request
});

Custom responses

Sometimes you may want to use your response class. This is useful if you want to add your methods or overwrite Saloon's response methods. Saloon allows you to overwrite the response at a connector level for all requests or at a per-request level for a granular response.
You may extend the Saloon\Http\Response class or provide your own implementation with the Saloon\Contracts\Response interface. You may use the HasResponseHelpers middleware when making your own implementation to save defining every method.

Using the response property

The simplest way of registering a custom response is to use the $response property on either the connector or request.
Connector
Request
<?php
​
use Saloon\Http\Connector;
​
class ForgeConnector extends Connector
{
// {...}
protected ?string $response = CustomResponse::class;
}
<?php
​
use Saloon\Http\Request;
​
class GetServersRequest extends Request
{
// {...}
protected ?string $response = CustomResponse::class;
}

Using the resolveResponseClass method

When you need a more advanced way to define a custom response, use the resolveResponseClass method on either the connector or request.
Connector
Request
<?php
​
use Saloon\Http\Connector;
​
class ForgeConnector extends Connector
{
// {...}
public function resolveResponseClass(): string
{
return CustomResponse::class;
}
}
<?php
​
use Saloon\Http\Request;
​
class GetServersRequest extends Request
{
// {...}
public function resolveResponseClass(): string
{
return CustomResponse::class;
}
}