📡Responses

After sending a request, Saloon will return a Response class. This response class contains many helpful methods for interacting with your HTTP response like seeing the HTTP status code and retrieving the body.

<?php

$forge = new ForgeConnector;
$request = new GetServersRequest;

$response = $forge->send($request);

$status = $response->status();
$body = $response->body();

By default, Saloon will not throw an exception if a synchronous request fails. Refer to the handling failures section for handling errors.

Useful Methods

Below are some of the key methods provided by Saloon's Response class.

Method	Description
status	Returns the response status code.
headers	Returns all response headers
header	Returns a given header
body	Returns the raw response body as a string
json	Retrieves a JSON response body and json_decodes it into an array.
array	Alias of json
collect	Retrieves a JSON response body and json_decodes it into a Laravel Collection. Requires illuminate/collections.
object	Retrieves a JSON response body and json_decodes it into an object.
xmlReader	Used for XML responses - returns a XML Wrangler reader. Requires saloonphp/xml-wrangler.
dom	Used for HTML responses - returns a Symfony DOM Crawler instance. Requires symfony/dom-crawler.
stream	Returns the response body as an instance of StreamInterface
saveBodyToFile	Allows you to save the raw body to a file or open file resource.
dto	Converts the response into a data-transfer object. You must define your DTO first, click here to read more.
dtoOrFail	Will work just like dto but will throw an exception if the response is considered "failed".
ok, successful, redirect, failed, clientError, serverError	Methods used to determine if a request was successful or not based on status code. The failed method can be customised.
throw	Will throw an exception if the response is considered "failed".
getPendingRequest	Returns the PendingRequest class that was built up for the request.
getPsrRequest	Returns the PSR-7 request that was built up by Saloon
getPsrResponse	Return the PSR-7 response that was built up by the HTTP client/sender.

Asynchronous Responses

When sendAsync or concurrent requests, 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\Http\Response;

$forge = new ForgeConnector;
$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.

The simplest way of registering a custom response is to use the $response property on either the connector or request.

Connector

class ForgeConnector extends Connector
{
    // ...
    
    protected ?string $response = CustomResponse::class;
}

Request

class GetServersRequest extends Request
{
    // ...
    
    protected ?string $response = CustomResponse::class;
}

When you need a more advanced way to define a custom response, use the resolveResponseClass method on either the connector or request.

Connector

class ForgeConnector extends Connector
{
    // ...
    
    public function resolveResponseClass(): string
    {
        return CustomResponse::class;
    }
}

Request

class GetServersRequest extends Request
{
    // ...
    
    public function resolveResponseClass(): string
    {
        return CustomResponse::class;
    }
}