<?php
use Saloon\Http\Request;
use Saloon\Http\PendingRequest;
use Saloon\Enums\PipeOrder;
class GetServersRequest extends Request
{
// { ... }
public function boot(PendingRequest $pendingRequest): void
{
$request->middleware()->onRequest(new RecordResponse, order: PipeOrder::LAST);
}
}
<?php
use Saloon\Http\Request;
use Saloon\Http\OAuth2\GetClientCredentialsTokenRequest;
protected function defaultOauthConfig(): OAuthConfig
{
return OAuthConfig::make()
->setClientId('my-client-id')
->setClientSecret('my-client-secret')
->setRequestModifier(function (GetClientCredentialsTokenRequest $request) {
//
}),
}
<?php
use Saloon\Http\Connector;
use Saloon\Traits\OAuth2\AuthorizationCodeGrant;
class SpotifyConnector extends Connector
{
use AuthorizationCodeGrant;
public function __construct(string $clientId, string $clientSecret)
{
$this->oauthConfig()->setClientId($clientId);
$this->oauthConfig()->setClientSecret($clientSecret);
}
// ...
}
<?php
$connector = new SpotifyConnector;
$authorizationUrl = $connector->getAuthorizationUrl();
$state = $authConnector->getState(); // '8484b43fdjfdnfdj3llls...'
<?php
$connector = new SpotifyConnector;
$authenticator = $authConnector->getAccessToken($code);
// Use authenticator to authenticate your connector instance
$connector->authenticate($authenticator);
// Any request sent through this connector will now have authentication applied
$connector->send(new GetTracksRequest);
<?php
use Saloon\Http\Response;
use Saloon\Http\Connector;
use Saloon\PaginationPlugin\CursorPaginator;
use Saloon\PaginationPlugin\Contracts\HasPagination;
class SpotifyConnector extends Connector implements HasPagination
{
// ...
public function paginate(Request $request): CursorPaginator
{
return new class(connector: $this, request: $request) extends CursorPaginator
{
//
};
}
}
{% hint style="info" %}
You don't need to use an anonymous class if it doesn't fit your code style. It is recommended to reduce the number of classes, but you can create your own pagination class that extends the base paginator if you prefer.
{% endhint %}
After you have defined your paginator class, you will be required to define three protected methods which are used to power the paginator. These methods are:
* **getNextCursor** - This method is used to find the next cursor from the response. This method must return either an integer or a string. The next cursor is used in the next request to get a different page.
* **isLastPage** - This method is used to tell the paginator when to stop processing. Here you can use the response class provided to determine if you are on the last page. Some APIs may provide metadata like remaining results or next page URLs which you can use to check if you are on the last page. Additionally, Saloon has a few properties that can be used to determine if you are on the last page.
* **getPageItems** - This method is used to return the array of results inside of each page. This is used when using the `items` or `collect` method on your paginator class.
Let's implement these three methods on our paginator and dive into how it works.
<?php
use Saloon\Http\Response;
use Saloon\Http\Connector;
use Saloon\PaginationPlugin\CursorPaginator;
use Saloon\PaginationPlugin\Contracts\HasPagination;
class SpotifyConnector extends Connector implements HasPagination
{
// ...
public function paginate(Request $request): CursorPaginator
{
return new class(connector: $this, request: $request) extends CursorPaginator
{
protected function getNextCursor(Response $response): int|string
{
return $response->json('next_cursor');
}
protected function isLastPage(Response $response): bool
{
return is_null($response->json('next_cursor'));
}
protected function getPageItems(Response $response, Request $request): array
{
return $response->json('items');
}
};
}
}
public function paginate(Request $request): CursorPaginator
{
return new class(connector: $this, request: $request) extends CursorPaginator
{
protected ?int $perPageLimit = 100;
// ...
}
}
public function paginate(Request $request): CursorPaginator
{
return new class(connector: $this, request: $request) extends CursorPaginator
{
protected function getNextCursor(Response $response): int|string
{
return $response->json('next_cursor');
}
protected function isLastPage(Response $response): bool
{
return is_null($response->json('next_cursor'));
}
protected function getPageItems(Response $response, Request $request): array
{
return $response->json('items');
}
protected function applyPagination(Request $request): Request
{
if ($this->currentResponse instanceof Response) {
$request->query()->add('pageCursor', $this->getNextCursor($this->currentResponse));
}
if (isset($this->perPageLimit)) {
$request->query()->add('pageSize', $this->perPageLimit);
}
return $request;
}
};
}
<?php
use Saloon\Http\Response;
use Saloon\Http\Connector;
use Saloon\PaginationPlugin\Paginator;
use Saloon\PaginationPlugin\Contracts\HasPagination;
class SpotifyConnector extends Connector implements HasPagination
{
// ...
public function paginate(Request $request): Paginator
{
return new class(connector: $this, request: $request) extends Paginator
{
//
};
}
}
{% hint style="info" %}
You don't need to use an anonymous class if it doesn't fit your code style. It is recommended to reduce the number of classes, but you can create your own pagination class that extends the base paginator if you prefer.
{% endhint %}
After you have defined your paginator class, you will be required to define three protected methods which are used to power the paginator. These methods are:
* **isLastPage** - This method is used to tell the paginator when to stop processing. Here you can use the response class provided to determine if you are on the last page. Some APIs may provide metadata like remaining results or next page URLs which you can use to check if you are on the last page. Additionally, Saloon has a few properties that can be used to determine if you are on the last page.
* **getPageItems** - This method is used to return the array of results inside of each page. This is used when using the `items` or `collect` method on your paginator class.
* **applyPagination** - This method is used to change each request to apply the pagination for the next page.
Let's implement these three methods on our paginator and dive into how it works.
<?php
use Saloon\Http\Response;
use Saloon\Http\Connector;
use Saloon\PaginationPlugin\Paginator;
use Saloon\PaginationPlugin\Contracts\HasPagination;
class SpotifyConnector extends Connector implements HasPagination
{
// ...
public function paginate(Request $request): Paginator
{
return new class(connector: $this, request: $request) extends Paginator
{
protected function isLastPage(Response $response): bool
{
return is_null($response->json('next_page_url'));
}
protected function getPageItems(Response $response, Request $request): array
{
return $response->json('items');
}
protected function applyPagination(Request $request): Request
{
$request->headers()->add('X-Page', $this->currentPage);
$request->headers()->add('X-Per-Page', $this->perPageLimit);
return $request;
}
};
}
}
public function paginate(Request $request): Paginator
{
return new class(connector: $this, request: $request) extends Paginator
{
protected ?int $perPageLimit = 100;
// ...
};
}
<?php
use Saloon\Http\Response;
use Saloon\Http\Connector;
use Saloon\PaginationPlugin\OffsetPaginator;
use Saloon\PaginationPlugin\Contracts\HasPagination;
class SpotifyConnector extends Connector implements HasPagination
{
// ...
public function paginate(Request $request): OffsetPaginator
{
return new class(connector: $this, request: $request) extends OffsetPaginator
{
//
};
}
}
{% hint style="info" %}
You don't need to use an anonymous class if it doesn't fit your code style. It is recommended to reduce the number of classes, but you can create your own pagination class that extends the base paginator if you prefer.
{% endhint %}
After you have defined your paginator class, you will be required to define a single property and two protected methods which are used to power the paginator. These properties/methods are:
* **perPageLimit** - This property is required as this is the default limit of the paginator. Since this paginator requires limit/offset - the limit is always required. If you need to change the limit on a per-request basis you can change it on the paginator instance.
* **isLastPage** - This method is used to tell the paginator when to stop processing. Here, you can use the response class provided to determine if you are on the last page. Some APIs may provide metadata like remaining results or next-page URLs, which you can use to check if you are on the last page. Additionally, Saloon has a few properties that can be used to determine if you are on the last page.
* **getPageItems** - This method is used to return the array of results inside of each page. This is used when using the `items` or `collect` method on your paginator class.
Let's implement the property and the two methods on our paginator and dive into how it works.
<?php
use Saloon\Http\Response;
use Saloon\Http\Connector;
use Saloon\PaginationPlugin\OffsetPaginator;
use Saloon\PaginationPlugin\Contracts\HasPagination;
class SpotifyConnector extends Connector implements HasPagination
{
// ...
public function paginate(Request $request): OffsetPaginator
{
return new class(connector: $this, request: $request) extends OffsetPaginator
{
protected ?int $perPageLimit = 100;
protected function isLastPage(Response $response): bool
{
return $this->getOffset() >= (int)$response->json('total');
}
protected function getPageItems(Response $response, Request $request): array
{
return $response->json('items');
}
};
}
}
public function paginate(Request $request): OffsetPaginator
{
return new class(connector: $this, request: $request) extends OffsetPaginator
{
protected ?int $perPageLimit = 100;
protected function isLastPage(Response $response): bool
{
return $this->getOffset() >= (int)$response->json('total');
}
protected function getPageItems(Response $response, Request $request): array
{
return $response->json('items');
}
protected function applyPagination(Request $request): Request
{
$request->query()->merge([
'top' => $this->perPageLimit,
'skip' => $this->getOffset(),
]);
return $request;
}
};
}
<?php
use Saloon\Http\Response;
use Saloon\Http\Connector;
use Saloon\PaginationPlugin\PagedPaginator;
use Saloon\PaginationPlugin\Contracts\HasPagination;
class SpotifyConnector extends Connector implements HasPagination
{
// ...
public function paginate(Request $request): PagedPaginator
{
return new class(connector: $this, request: $request) extends PagedPaginator
{
//
};
}
}
{% hint style="info" %}
You don't need to use an anonymous class if it doesn't fit your code style. It is recommended to reduce the number of classes, but you can create your own pagination class that extends the base paginator if you prefer.
{% endhint %}
After you have defined your paginator class, you will be required to define two protected methods which are used to power the paginator. These methods are:
* **isLastPage** - This method is used to tell the paginator when to stop processing. Here you can use the response class provided to determine if you are on the last page. Some APIs may provide metadata like remaining results or next page URLs which you can use to check if you are on the last page. Additionally, Saloon has a few properties that can be used to determine if you are on the last page.
* **getPageItems** - This method is used to return the array of results inside of each page. This is used when using the `items` or `collect` method on your paginator class.
Let's implement these two methods on our paginator and dive into how it works.
```php
json('next_page_url'));
}
protected function getPageItems(Response $response, Request $request): array
{
return $response->json('items');
}
};
}
}
```
Let's assume in this hypothetical example that the API provides some useful information to see if we're on the last page. In this example, we know we're on the last page if the `next_page_url` JSON property on the body is null. There are various other ways of knowing if you are on the last page, so it's best to fully understand your API's pagination.
To get the page items, we'll use the `json` method on the response to access the `items` array from the body.
### Specifying a default per-page on the paginator
The third-party API you are integrating with may require you to define a page size (per page) on your requests, or you may want to set a default page size used for every request. You can set this default page size as a property on the paginator class.
public function paginate(Request $request): PagedPaginator
{
return new class(connector: $this, request: $request) extends PagedPaginator
{
protected ?int $perPageLimit = 100;
// ...
}
}
public function paginate(Request $request): PagedPaginator
{
return new class(connector: $this, request: $request) extends PagedPaginator
{
protected function isLastPage(Response $response): bool
{
return is_null($response->json('next_page_url'));
}
protected function getPageItems(Response $response, Request $request): array
{
return $response->json('items');
}
protected function applyPagination(Request $request): Request
{
$request->query()->add('currentPage', $this->currentPage);
if (isset($this->perPageLimit)) {
$request->query()->add('pageSize', $this->perPageLimit);
}
return $request;
}
};
}
<?php
use Saloon\Http\Request;
use Saloon\PaginationPlugin\Contracts\Paginatable;
class GetLikedSongsRequest extends Request implements Paginatable
{
// ...
}
<?php
use Saloon\Http\Connector;
use Saloon\PaginationPlugin\Paginator;
use Saloon\PaginationPlugin\Contracts\HasPagination;
class SpotifyConnector extends Connector implements HasPagination
{
// ...
public function paginate(Request $request): Paginator
{
//
}
}
<?php
$spotifyConnector = new SpotifyConnector;
$paginator = $spotifyConnector->paginate(new GetLikedSongsRequest);
$collection = $paginator->collect(throughItems: false);
class SpotifyConnector extends Connector implements HasPagination
{
public function paginate(Request $request): PagedPaginator
{
return new class(connector: $this, request: $request) extends PagedPaginator
{
// ...
protected function getPageItems(Response $response, Request $request): array
{
return $response->dto();
}
}
}
}
<?php
class GetLikedSongsRequest extends Request
{
// {...}
public function createDtoFromResponse(Response $response): array
{
return array_map(function (array $song) {
return Song::fromArray($song);
}, $response->json('items'));
}
}
<?php
class SpotifyConnector extends Connector implements HasPagination
{
public function paginate(Request $request): PagedPaginator
{
return new class(connector: $this, request: $request) extends PagedPaginator
{
// ...
protected function getTotalPages(Response $response): int
{
return $response->json('total_results');
}
}
}
}
<?php
$spotifyConnector = new SpotifyConnector;
$paginator = $spotifyConnector->paginate(new GetLikedSongsRequest);
$paginator->async();
foreach($paginator as $promise) {
// $promise->then()
}
<?php
$spotifyConnector = new SpotifyConnector;
$paginator = $spotifyConnector->paginate(new GetLikedSongsRequest);
$pool = $paginator->pool(concurrency: 10);
$pool->withResponseHandler(function (Response $response) {
// Handle each response
$status = $response->status();
$data = $response->body();
});
$promise = $pool->send();
$promise->wait();
<?php
$spotifyConnector = new SpotifyConnector;
$request = new GetLikedSongsRequest;
$paginator = $request->paginate($spotifyConnector);
<?php
$spotifyConnector = new SpotifyConnector;
$paginator = $spotifyConnector->paginate(new GetLikedSongsRequest);
$pages = count($paginator);
public function paginate(Connector $connector): Paginator;
{
return new class(connector: $connector, request: $this) extends PagedPaginator
{
protected bool $detectInfiniteLoop = false;
}
}
class ForgeConnector extends Connector
{
public ?int $tries = 3;
}
Now when we send any request through this connector, if it fails it will be retried.
```php
$forgeConnector = new ForgeConnector;
$response = $forgeConnector->send(new UnreliableRequest);
```
If we get to attempt three and it still fails, Saloon will throw a `FatalRequestException` (for connection errors) or a `RequestException` for typical HTTP errors.
{% hint style="warning" %}
The retry functionality will only work when sending requests synchronously. The retry logic will not work when using `sendAsync` or pools because Saloon needs to wait for a response to come back to determine if it needs to be retried.
{% endhint %}
#### What does Saloon consider a failed request?
By default, if the API couldn't be connected to or if the response status code is either a 4xx or 5xx, then Saloon will consider it a failed request. You can change this by extending the `hasRequestFailed` method on your connector. [Click here to learn more.](../the-basics/handling-failures.md#customising-when-saloon-thinks-a-request-has-failed)
### Intervals
You can also configure an interval in **milliseconds** that Saloon should wait between retries. You can configure an interval with the `$retryInterval` property.
class ForgeConnector extends Connector
{
public ?int $tries = 3;
public ?int $retryInterval = 1000;
}
class ForgeConnector extends Connector
{
public ?int $tries = 3;
public ?int $retryInterval = 500;
public ?bool $useExponentialBackoff = true;
}
class ForgeConnector extends Connector
{
public ?int $tries = 3;
public ?bool $throwOnMaxTries = false;
}
<?php
use Saloon\Exceptions\RequestException;
use Saloon\Http\Auth\TokenAuthenticator;
use Saloon\Exceptions\FatalRequestException;
use Saloon\Http\Request;
class ForgeConnector extends Connector
{
public ?int $tries = 3;
public function handleRetry(FatalRequestException|RequestException $exception, Request $request): bool
{
if ($exception instanceof RequestException && $exception->getResponse()->status() === 401) {
$request->authenticate(new TokenAuthenticator($this->getNewToken()));
}
return true;
}
}
use Saloon\Http\Connector;
use Saloon\RateLimitPlugin\Stores\MemoryStore;
use Saloon\RateLimitPlugin\Traits\HasRateLimits;
class SpotifyConnector extends Connector
{
use HasRateLimits;
public function __construct()
{
$this->detectTooManyAttempts = false;
}
}
use Saloon\Http\Connector;
use Saloon\RateLimitPlugin\Stores\MemoryStore;
use Saloon\RateLimitPlugin\Traits\HasRateLimits;
class SpotifyConnector extends Connector
{
use HasRateLimits;
protected function getTooManyAttemptsLimiter(): ?Limit
{
return Limit::custom($this->handleTooManyAttempts(...))->sleep();
}
}
use Saloon\Http\Connector;
use Saloon\RateLimitPlugin\Traits\HasRateLimits;
class SpotifyConnector extends Connector
{
use HasRateLimits;
public function __construct()
{
$this->rateLimitingEnabled = false;
}
}
// Or...
$connector = new SpotifyConnector;
$connector->useRateLimitPlugin(false);
--oauth option if you would like to create an OAuth2 connector..png)
<?php
trait HasLogging
{
public function bootHasLogging(PendingRequest $pendingRequest): void
{
ray($pendingRequest);
}
}
{% hint style="warning" %}
You must not use `$this` inside of the trait, as mutating the original request or connector is discouraged. The PendingRequest is the source of truth while a request is being sent.
{% endhint %}
{% endtab %}
{% tab title="Usage (Connector)" %}
<?php
class ForgeConnector extends Connector
{
use HasLogging;
}
.png)
Introducing Saloon v3
<?php
use Saloon\Http\BaseResource;
use Saloon\Http\Response;
class PokemonResource extends BaseResource
{
public function all(int $page): Response
{
return $this->connector->send(new GetAllPokemon($page));
}
public function get(int $id): Response
{
return $this->connector->send(new GetSinglePokemon($id));
}
}
class ForgeConnector extends Connector
{
// ...
protected function defaultHeaders(): array
{
return [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
];
}
}
<?php
use Saloon\Http\Request;
use Saloon\Enums\Method;
use Saloon\Http\Response;
use Saloon\Contracts\Body\HasBody;
use Saloon\Traits\Body\HasJsonBody;
class UpdateServerRequest extends Request implements HasBody
{
use HasJsonBody;
protected Method $method = Method::PUT;
public function __construct(readonly protected Server $server)
{
//
}
public function resolveEndpoint(): string
{
return '/servers/' . $this->server->id;
}
protected function defaultBody(): array
{
return [
'name' => $this->server->name,
];
}
public function createDtoFromResponse(Response $response): mixed
{
$data = $response->json();
return new Server(
id: $data['id'],
name: $data['name'],
ipAddress: $data['ip'],
);
}
}
<?php
use Saloon\Http\Response;
use Saloon\Traits\Responses\HasResponse;
use Saloon\Contracts\DataObjects\WithResponse;
class Server implements WithResponse
{
use HasResponse;
public function __construct(
public readonly int $id,
public readonly string $name,
public readonly string $ipAddress,
){}
}
<?php
use Saloon\Http\Connector;
use Saloon\Http\Response;
class ForgeConnector extends Connector
{
// {...}
public function hasRequestFailed(Response $response): ?bool
{
return str_contains($response->body(), 'Server Error');
}
}
<?php
use Saloon\Http\Request;
use Saloon\Http\Response;
class ErrorRequest extends Request
{
// {...}
public function hasRequestFailed(Response $response): ?bool
{
return str_contains($response->body(), 'Server Error');
}
}
<?php
use Saloon\Http\Request;
use Saloon\Contracts\Body\HasBody;
class CreateServerRequest extends Request implements HasBody
{
protected Method $method = Method::POST;
}
Next, you will need to add the `HasFormBody` trait to your request. This trait will implement the `body()` method that the `HasBody` interface requires. It also provides a method `defaultBody()` which you can extend to provide a default body on your request.
<?php
use Saloon\Http\Request;
use Saloon\Contracts\Body\HasBody;
use Saloon\Traits\Body\HasFormBody;
class CreateServerRequest extends Request implements HasBody
{
use HasFormBody;
protected Method $method = Method::POST;
}
<?php
use Saloon\Http\Request;
use Saloon\Contracts\Body\HasBody;
use Saloon\Traits\Body\HasFormBody;
class CreateServerRequest extends Request implements HasBody
{
use HasFormBody;
protected Method $method = Method::POST;
public function __construct(
protected Server $server
){}
protected function defaultBody(): array
{
return [
'ubuntu_version' => $this->server->ubuntuVersion,
'type' => $this->server->type,
'provider' => $this->server->provider,
];
}
}
<?php
use Saloon\Http\Request;
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
class CreateServerRequest extends Request implements HasBody
{
protected Method $method = Method::POST;
}
Next, you will need to add the `HasJsonBody` trait to your request. This trait will implement the `body()` method that the `HasBody` interface requires. It also provides a method `defaultBody()` which you can extend to provide a default body on your request.
<?php
use Saloon\Http\Request;
use Saloon\Contracts\Body\HasBody;
use Saloon\Traits\Body\HasJsonBody;
class CreateServerRequest extends Request implements HasBody
{
use HasJsonBody;
protected Method $method = Method::POST;
}
<?php
use Saloon\Http\Request;
use Saloon\Contracts\Body\HasBody;
use Saloon\Traits\Body\HasJsonBody;
class CreateServerRequest extends Request implements HasBody
{
use HasJsonBody;
protected Method $method = Method::POST;
public function __construct(
protected Server $server
){}
protected function defaultBody(): array
{
return [
'ubuntu_version' => $this->server->ubuntuVersion,
'type' => $this->server->type,
'provider' => $this->server->provider,
];
}
}
<?php
use Saloon\Http\Request;
use Saloon\Contracts\Body\HasBody;
class UploadProfilePictureRequest extends Request implements HasBody
{
protected Method $method = Method::POST;
}
Next, you will need to add the `HasMultipartBody` trait to your request. This trait will implement the `body()` method that the `HasBody` interface requires. It also provides a method `defaultBody()` which you can extend to provide a default body on your request.
<?php
use Saloon\Http\Request;
use Saloon\Contracts\Body\HasBody;
use Saloon\Traits\Body\HasMultipartBody;
class UploadProfilePictureRequest extends Request implements HasBody
{
use HasMultipartBody;
protected Method $method = Method::POST;
}
<?php
use Saloon\Http\Request;
use Saloon\Contracts\Body\HasBody;
class CreateServerRequest extends Request implements HasBody
{
protected Method $method = Method::POST;
}
Next, you will need to add a trait to provide an implementation for the missing `body()` method. Saloon has a trait for all the common types of request bodies.
Continue reading below to understand more about the specific body type that you need.
{% content-ref url="json-body.md" %}
[json-body.md](json-body.md)
{% endcontent-ref %}
{% content-ref url="multipart-form-body.md" %}
[multipart-form-body.md](multipart-form-body.md)
{% endcontent-ref %}
{% content-ref url="stream-body.md" %}
[stream-body.md](stream-body.md)
{% endcontent-ref %}
{% content-ref url="form-body-url-encoded.md" %}
[form-body-url-encoded.md](form-body-url-encoded.md)
{% endcontent-ref %}
{% content-ref url="xml-body.md" %}
[xml-body.md](xml-body.md)
{% endcontent-ref %}
{% content-ref url="string-plain-text-body.md" %}
[string-plain-text-body.md](string-plain-text-body.md)
{% endcontent-ref %}
]]>
<?php
use Saloon\Http\Request;
use Saloon\Contracts\Body\HasBody;
class CreateServerRequest extends Request implements HasBody
{
protected Method $method = Method::POST;
}
Next, you will need to add the `HasBody` trait to your request. This trait will implement the `body()` method that the `HasBody` interface requires. It also provides a method `defaultBody()` which you can extend to provide a default body on your request.
<?php
use Saloon\Http\Request;
use Saloon\Contracts\Body\HasBody;
use Saloon\Traits\Body\HasStreamBody;
class CreateServerRequest extends Request implements HasBody
{
use HasStreamBody;
protected Method $method = Method::POST;
// Define our own Content-Type...
protected function defaultHeaders(): array
{
return [
'Content-Type' => 'text/plain',
];
}
}
<?php
use Saloon\Http\Request;
use Saloon\Contracts\Body\HasBody;
class CreateServerRequest extends Request implements HasBody
{
protected Method $method = Method::POST;
}
Next, you will need to add the `HasStringBody` trait to your request. This trait will implement the `body()` method that the `HasBody` interface requires. It also provides a method `defaultBody()` which you can extend to provide a default body on your request.
<?php
use Saloon\Http\Request;
use Saloon\Contracts\Body\HasBody;
use Saloon\Traits\Body\HasStringBody;
class CreateServerRequest extends Request implements HasBody
{
use HasStringBody;
protected Method $method = Method::POST;
// Define our own Content-Type...
protected function defaultHeaders(): array
{
return [
'Content-Type' => 'text/plain',
];
}
}
<?php
use Saloon\Http\Request;
use Saloon\Contracts\Body\HasBody;
use Saloon\Traits\Body\HasStringBody;
class CreateServerRequest extends Request implements HasBody
{
use HasStringBody;
protected Method $method = Method::POST;
public function __construct(
protected string $ubuntuVersion,
protected string $provider
){}
protected function defaultBody(): string
{
return 'Howdy, Partner. I want a ' . $this->ubuntuVersion . ' server through ' . $this->provider . ' provider!';
}
}
<?php
use Saloon\Http\Request;
use Saloon\Contracts\Body\HasBody;
class CreateServerRequest extends Request implements HasBody
{
protected Method $method = Method::POST;
}
Next, you will need to add the `HasXmlBody` trait to your request. This trait will implement the `body()` method that the `HasBody` interface requires. It also provides a method `defaultBody()` which you can extend to provide a default body on your request.
<?php
use Saloon\Http\Request;
use Saloon\Contracts\Body\HasBody;
use Saloon\Traits\Body\HasXmlBody;
class CreateServerRequest extends Request implements HasBody
{
use HasXmlBody;
protected Method $method = Method::POST;
}
| 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. |
class ForgeConnector extends Connector
{
// ...
protected ?string $response = CustomResponse::class;
}
class GetServersRequest extends Request
{
// ...
protected ?string $response = CustomResponse::class;
}
<?php
use Saloon\Http\Faking\MockClient;
use Saloon\Http\Faking\MockResponse;
test('can store servers in the database from laravel forge', function () {
MockClient::global([
GetServersRequest::class => MockResponse::fixture('servers'),
]);
$this->assertDatabaseCount('servers', 0);
// Call our controller which will invoke the Saloon request
$this
->getJson('/api/servers/sync')
->assertOk();
// Assert our database has created servers!
$this->assertDatabaseCount('servers', 2);
$this->assertDatabaseHas('servers', [
'name' => 'REAL-SERVER-1',
'ip' => '192.168.0.1',
]);
$this->assertDatabaseHas('servers', [
'name' => 'REAL-SERVER-2',
'ip' => '192.168.0.2',
]);
});
<?php
test('a request sends the correct body', function () {
$mockClient = new MockClient([
CreateServerRequest::class => MockResponse::make('Server Created', 200),
]);
$connector = new ForgeConnector;
$connector->withMockClient($mockClient);
$connector->send(new CreateServerRequest($name, $ip));
$mockClient->assertSent(function (Request $request) {
return $request->body()->all() === ['name' => $name, 'ip' => $ip];
});
});
<?php
namespace Tests\Fixtures\Forge\SingleServerFixture;
use Saloon\Http\Faking\Fixture;
class SingleServerFixture extends Fixture
{
protected function defineName(): string
{
return 'forge/singleServer';
}
protected function defineSensitiveHeaders(): array
{
return [
'Authorization' => 'REDACTED',
];
}
protected function defineSensitiveJsonParameters(): array
{
return [
'name' => 'REDACTED',
'password' => function () {
return faker()->password;
},
];
}
protected function defineSensitiveRegexPatterns(): array
{
return [
'/@[a-z0-9_]{0,100}/' => 'REDACTED-TWITTER-HANDLE',
];
}
}
<?php
$mockClient = new MockClient([
GetServerRequest::class => new SingleServerFixture;
]);
use Saloon\Contracts\Connectoruse Saloon\Http\Connectoruse Saloon\Contracts\Requestuse Saloon\Http\Requestuse Saloon\Contracts\PendingRequestuse Saloon\Http\PendingRequestuse Saloon\Contracts\Responseuse Saloon\Http\Response| Find | Replace |
|---|---|
use Saloon\Traits\Body\HasBody | use Saloon\Traits\Body\HasStringBody |
use HasBody | use HasStringBody |
$connector->sendAndRetry(
request: $request,
tries: 5,
);
$connector->sendAndRetry(
request: $request,
tries: 5,
interval: 0,
handleRetry: static function (Throwable $exception, Request $request) {
// $request->headers()->add();
},
);
| Old | Suggested Replacement |
|---|---|
$pendingRequest->send() | $pendingRequest->getConnector()->send() |
$pendingRequest->sendAsync() | $pendingRequest->getConnector()->sendAsync() |
$pendingRequest->getSender() | $pendingRequest->getConnector()->sender() |