🌳Upgrading from v2

Saloon version three comes with many improvements over version two, but most of the improvements were internal changes, so the upgrade to v3 from v2 shouldn't be too cumbersome. If you haven't already, it's recommended to read through "What's new in v3" to get an idea of what has changed before making the upgrade.

Upgrade Saloon's Packages

First of all, you should bump Saloon to the next major version in your composer.json file. You should also update any of the following plugins if you have them installed.

• saloonphp/saloon to ^3.0

• saloonphp/laravel-plugin to ^3.0

• saloonphp/cache-plugin to ^3.0

• saloonphp/laravel-http-sender to ^2.0

• saloonphp/rate-limit-plugin to ^2.0

• saloonphp/pagination-plugin to ^2.0

After that, make sure to run the following command to update your composer.lock file and your vendor directory.

composer update "saloonphp/*"

The above command will just update the saloonphp libraries. If you have other libraries using Saloon you should make sure that they are updated as well.

High Impact Changes

High-impact changes will most likely be things that everyone needs to update.

Minimum TLS 1.2 version enforced

From version three, Saloon uses Guzzle ^7.6 which introduced a new option to configure a minimum TLS version. With Saloon v3, Saloon has set this default to TLS 1.2. If any of your API integrations require a lower level of TLS security, you can change the Saloon config while your application is loading.

<?php

use Saloon\Config;

Config::$defaultTlsMethod = STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT;

You can visit this page on the PHP documentation to see the different TLS options available.

TLS 1.1 has been deprecated since 2021 so it is unlikely that APIs are still using it, but older systems may have not upgraded yet.

New Paginators

With version three, paginators are no longer included in the core Saloon library and have been moved to a plugin. Additionally, the paginators have been completely rebuilt. Review if you have used any of the pagination functionality and follow the new pagination guide to rebuild them in the new way.

Config and MockConfig classes have moved

Previously, Saloon's Config and MockConfig classes lived in a Saloon\Helpers directory. These classes have now been moved to the root Saloon namespace. You should update your use statements to the new namespace.

Find	Replace
use Saloon\Helpers\Config	use Saloon\Config
use Saloon\Helpers\MockConfig	use Saloon\MockConfig

Core Interfaces Removed

Another decision that was made was to backtrack on the interfaces that were added in Saloon v2. This may not affect your integration, but a lot of the code examples and recommendations in v2 suggested using the contracts instead of the abstract classes, so you may have a few places in your application where you have imported the interface and not the class. You should find and replace the following main interfaces.

Find	Replace
use Saloon\Contracts\Connector	use Saloon\Http\Connector
use Saloon\Contracts\Request	use Saloon\Http\Request
use Saloon\Contracts\PendingRequest	use Saloon\Http\PendingRequest
use Saloon\Contracts\Response	use Saloon\Http\Response

There have been many other interfaces removed in v3 however it's unlikely that your application would have used them. They are listed below.

HasBody Trait Renamed to HasStringBody

During some of the code review to improve readability, the HasBody body trait has been renamed to HasStringBody to be more explicit. If any of your requests send a plain string body, you should find and replace this trait.

Find	Replace
use Saloon\Traits\Body\HasBody	use Saloon\Traits\Body\HasStringBody
use HasBody	use HasStringBody

Medium Impact Changes

Medium-impact changes are changes that come up for some people but not others.

SendAndRetry method argument name changes

The second argument of the $connector->sendAndRetry() method has been renamed from maxAttempts to tries. If you are using named arguments then you will need to replace this name.

$connector->sendAndRetry(
    request: $request,
    tries: 5,
);

SendAndRetry handler now expects a Request class and not PendingRequest

If you previously used the handleRetry argument when using $connector->sendAndRetry() - Saloon will now send an instance of Request instead of PendingRequest through the closure.

$connector->sendAndRetry(
    request: $request,
    tries: 5,
    interval: 0,
    handleRetry: static function (Throwable $exception, Request $request) {
        // $request->headers()->add();
    },
);

Config Method Changes

With version three, some of the methods in the Saloon\Config class have been renamed. These changes have been listed below and you should make sure to rename them if you have used them in your application.

Find	Replace
Config::middleware()	Config::globalMiddleware()
Config::resetMiddleware()	Config::clearGlobalMiddleware()
Config::resolveSenderWith()	Config::setSenderResolver()
Config::setDefaultSender()	Config::$defaultSender =

Low Impact Changes

Low-impact changes are changes that are unlikely to come up unless you have overwritten some of Saloon's functionality or used its interfaces. It's still worth looking through to make sure you haven't missed anything.

Methods Renamed On MockResponse

On the MockResponse class Saloon had a few methods which have now been renamed to be more consistent with the rest of Saloon. These changes are:

• getBody() has changed to body()

• getHeaders() has changed to headers()

• getStatus() has changed to status()

Middleware Arguments Changed

Saloon v3 introduced the ability to reorder middleware. With this, the old prepend argument on middleware methods has been replaced with a pipeOrder argument. Additionally, the second argument for the middleware is now name .

Methods Removed From PendingRequest Class

The following methods have now been removed from the PendingRequest class. You can use the suggested replacement if you are using them in your application.

Old	Suggested Replacement
$pendingRequest->send()	$pendingRequest->getConnector()->send()
$pendingRequest->sendAsync()	$pendingRequest->getConnector()->sendAsync()
$pendingRequest->getSender()	$pendingRequest->getConnector()->sender()

Promise Execution Changes

Previously, Saloon's PendingRequest and middleware would be invoked before an asynchronous request was sent (using $connector->sendAsync()) - now Saloon has fixed this issue and the PendingRequest and middleware will only be invoked while the Promise is being resolved - at the same time as sending the request. If your application depended on the old way the middleware was invoked you should make sure your application isn't affected by this change.

SimulatedResponsePayload Class Renamed

Previously, the MockResponse would extend a class called SimulatedResponsePayload. This class has now been renamed to FakeResponse. Additionally, methods on the PendingRequest like $pendingRequest->setSimulatedResponsePayload() has been renamed to $pendingRequest->setFakeResponse(). If you were extending the old class or using the methods to set the fake response in middleware, you should rename these methods.

Sender Contract Updated

The Sender interface has been completely rewritten in Saloon v3. Instead of just the sendRequest method. You now have to define three methods. If you have made a custom sender in Saloon, you should make sure this is updated.

<?php

interface Sender
{
    /**
     * Get the factory collection
     */
    public function getFactoryCollection(): FactoryCollection;

    /**
     * Send the request synchronously
     */
    public function send(PendingRequest $pendingRequest): Response;

    /**
     * Send the request asynchronously
     */
    public function sendAsync(PendingRequest $pendingRequest): PromiseInterface;
}

Date Helper Removed

Saloon v2 shipped with a simple Date helper class that wrapped around PHP's DateTime classes. This has now been removed in Saloon v3.

Other Helpers Renamed And Made Final

Saloon v2 shipped with a few helpers to reduce dependencies. The Str and Arr helper methods have been renamed to StringHelpers and ArrayHelpers respectively to prevent accidental imports when using Laravel. Saloon's internal helper classes have also been declared final as these shouldn't be extended or used by your application.

Other Interfaces (Contracts) Removed

As mentioned above, Saloon v3 removes a lot of interfaces that weren't adding value to the library. Alongside the ones mentioned above, these other interfaces have been removed.

Show Removed Interfaces

• src/Contracts/Arrayable.php

• src/Contracts/Authenticatable.php

• src/Contracts/CanThrowRequestExceptions.php

• src/Contracts/Connector.php

• src/Contracts/DebuggingDriver.php

• src/Contracts/Dispatcher.php

• src/Contracts/HasConfig.php

• src/Contracts/HasDebugging.php

• src/Contracts/HasDelay.php

• src/Contracts/HasHeaders.php

• src/Contracts/HasMiddlewarePipeline.php

• src/Contracts/HasMockClient.php

• src/Contracts/HasPagination.php

• src/Contracts/HasQueryParams.php

• src/Contracts/IntegerStore.php

• src/Contracts/MiddlewarePipeline.php

• src/Contracts/MockClient.php

• src/Contracts/Paginator.php

• src/Contracts/PendingRequest.php

• src/Contracts/Pipeline.php

• src/Contracts/Pool.php

• src/Contracts/Request.php

• src/Contracts/Response.php

• src/Contracts/SimulatedResponsePayload.php

The Base BodyRepository Class Is No Longer Stringable

If you have made your own BodyRepository class from the base class and relied on the __toString method this has now been removed. Additionally, the interface has been updated and now requires a toStream() method. Inside here, you must define how to convert your body type into a Stream using the provided StreamFactory.

Timeout Enum Removed

The old Timeout enum has now been removed. If your application used to use this method, you should migrate to use Config::$defaultConnectionTimeout and Config::$defaultRequestTimeout.

ToArray Method Removed From MultipartValue

Previously, the MultipartValue object had a toArray method. Now that all body repositories are converted into Streams, this method is no longer required.

SimulatedSender Removed

The SimulatedSender class which would be used if you were mocking or had a cached response has now been removed.

Did we miss anything?

If we forgot to add something to this upgrade please let us know by opening an issue.