Saloon: Reusable Request Classes for PHP API Integrations

The problem: API calls scattered across a PHP codebase

In a typical PHP application, HTTP calls to third parties end up wherever they are needed: a controller here, a queued job there, a service class somewhere else. Headers, base URLs, tokens and retry logic get copied between them. When the vendor changes an endpoint or a token scheme, you search the codebase and patch each site by hand.

Saloon's answer is to make the request itself a class. The README states that the library "moves your API requests into reusable classes so you can keep all your API configurations in one place." A connector object represents the API (its base URL, authentication, default headers) and a request class represents one endpoint. The application calls the connector with the request, and gets a response object back.

The audience follows from that. The README lists the target uses directly: teams that want "a standard everyone can follow", and people "building your next PHP SDK or library". If you are writing a client that other developers will install, the request-class shape doubles as your public API. If you are calling one endpoint once, this structure buys you nothing.

How Saloon works: connectors, request classes and Guzzle underneath

The library is built on top of Guzzle, which the README calls "the most popular and feature-rich HTTP client". Saloon does not replace Guzzle's transport; it organises the code that configures it. You define a connector for the service, then one request class per operation, and the connector's send method performs the call and returns a response.

The README's own example shows the shape of a call:

<?php

$forge = new ForgeConnector('api-token');

$response = $forge->send(new GetServersRequest);

$data = $response->json();

The connector is constructed with an API token, the request object is passed to send, and the response exposes the decoded body through json(). Everything specific to the Forge API lives in the connector and the request class rather than in the calling code.

Around that core, the README lists features that matter once integrations grow: request recording in tests, caching, OAuth2, pagination, request concurrency and data-transfer-object support. There is also full Laravel support, while the package itself is described as framework agnostic. The repository's top-level layout matches a normal Composer package: src/ for the code, tests/ for the suite, phpunit.xml and phpstan.dist.neon for tooling, plus a .php-cs-fixer.dist.php for style. Nothing in the README describes the internal pipeline beyond Guzzle, so treat the request lifecycle (how middleware, caching and retries are ordered) as something to read in the documentation before you rely on it.

Installing Saloon and making a first request

The README does not inline installation steps. It links to a getting-started page at docs.saloon.dev/getting-started/installation, and the package is distributed through Composer under the name saloonphp/saloon (the Packagist badge in the README points at that package).

After installing, the first real use is to define a connector for the API you are calling and a request class for one endpoint. The README's snippet is the target state: construct the connector with whatever credential the API needs, send a request instance, and read the decoded body from the response. For the concrete class definitions (what a connector extends, what a request class must implement, how the base URL and headers are declared), the documentation site is the source, since the README deliberately keeps the example short.

Expect to write two classes before your first call succeeds: one connector and one request. That is the cost of the pattern, and it is also the point of it. Once those exist, every later call to the same API is a new request class and nothing else.

Where Saloon is the wrong tool

The clearest failure mode is scale in the wrong direction. If your application talks to one API at one place in the code, a connector plus a request class is more files than a direct Guzzle call and gives you nothing in return. The README's own framing, reusable classes and a standard for a team, only pays off when there is repetition to remove.

A second boundary is the abstraction layer itself. Saloon sits on Guzzle, so anything Guzzle does not expose is not magically available, and debugging a failed call means understanding both Saloon's classes and the Guzzle stack beneath them. The README does not document an escape hatch for dropping to raw Guzzle mid-request, so if your integration depends on unusual transport behaviour, check the documentation before committing.

Third, the feature list is broad but the README is a summary. Caching, OAuth2, pagination and request recording are named, not specified. There is no statement in the README about rollback behaviour, about how caching keys are derived, or about what happens when a paginated response changes shape. Those are the areas to read up on rather than assume.

Saloon compared with calling Guzzle directly

The honest alternative is Guzzle itself, used without Saloon. Guzzle is the HTTP client Saloon builds on, and it already handles requests, responses, middleware and concurrency. If your codebase calls a handful of endpoints and you are comfortable with Guzzle's client and handler stack, staying there removes a dependency and a layer of indirection.

The difference is where the structure lives. With plain Guzzle, the request configuration is code you write at each call site or in your own wrapper; Saloon makes that configuration a class the framework and your IDE can see, and gives you a named place for each endpoint. That is the trade: Saloon adds a package and a convention in exchange for consistency across many integrations. Guzzle adds nothing and leaves the convention to you.

For an SDK you intend to publish, the Saloon shape is closer to what consumers expect, because each operation is a discoverable class. For an internal script that posts a form to one endpoint, plain Guzzle is the shorter path.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-18. The same date carries three releases: v4.3.0, v4.2.1 and v4.2.0, all published on 2026-09-18, and the default branch is v4. The README points contributors at a CONTRIBUTING file and a SECURITY policy in the repository, and the project has a test workflow configured in .github/.

The licence is MIT, which in practice means you can use, modify and redistribute the library, including in commercial and closed-source products, provided the licence and copyright notice are preserved. That is a summary of what MIT normally permits, not legal advice; read the LICENSE file in the repository for the actual terms.

Upgrade cost is a real consideration here. The default branch is v4, so the current line is a major version, and major versions of an HTTP abstraction tend to move class contracts. The README does not describe a migration path between major versions, so before upgrading an existing integration, check the documentation for an upgrade guide rather than assuming drop-in compatibility.

Editorial conclusion

Adopt Saloon when you have more than a couple of third-party APIs and want each call to live in a named class with its own configuration, or when you are publishing an SDK. Do not adopt it for a single endpoint you call once, where a direct Guzzle call is less ceremony. Verify first that the features you need (caching, OAuth2, pagination, request recording) are documented at docs.saloon.dev for the v4 branch, and confirm your PHP version against composer.json before installing.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. saloonphp/saloon on GitHub