Migrating to PSR-18 Support

[aidan-casey]

Hey @Sammyjo20! I appreciate the work you have put into this project. Only one thing has really stopped my team from adopting its use in a few areas: lack of PSR-18 support.

I am currently working on a PR proposal that would allow any PSR-18 compatible client to work and simply require the psr/http-client-implementation and psr/http-factory-implementation virtual packages. These can be configured by the developer in the sender, of course, but in an environment where they are already installed (e.g., Laravel) they will be automatically discovered and used. Assuming it is agreeable, I would propose dropping the Guzzle requirement entirely in version 3 and making this the primary driver.

There are a few challenges to this approach, however:

1. Async requests are not supported by default for PSR-18 clients. This is not really an issue, as there are various ways to make PSR requests async.
2. Currently various Guzzle options are being used (multipart, form, json, etc.) that would need to be translated into custom code to format the request body and headers. Again, not a big deal, but does add some upfront work.

So I have a few questions before I continue to go too far down this path...

First, is this something that is even interesting to you as you develop the project? I had seen a previous discussion about this (#50) where you seemed interested, but I just wanted to confirm before too much work was put in.

Second, assuming it is an interesting addition, is are there any features that are utilizing Guzzle that I am missing? I would hate to go backward in functionality. 🙂

[Sammyjo20]

Hey @aidan-casey just wanted to let you know that I’ve had a good read through your message and I’m going to think about it tonight. I’ll get back to you tomorrow! 😀

[aidan-casey]

Appreciate it! Sounds like a plan.

[Sammyjo20]

Hey @aidan-casey

This is an interesting proposal, so I can understand from your perspective, what is the why behind creating a PSR-18 compatible sender? I've had many people tell me "You should support PSR" but not many people explain why and most of the time it feels like it's "just because" and not give me any good examples but it would be good to fully understand and be in your shoes :)

I would be interested in this - It would be great in the future if Saloon had even fewer dependencies but for the moment I would rather if the PSR sender was built as a separate library and then you can install the sender on a per-project basis when V3 comes around we can discuss moving the code into the core codebase or requiring the library in the main package and dropping Guzzle. This allows you to have your own versioning away from Saloon as well as let people install it without any breaking changes. You may use my package template if you want the same one that Saloon uses: https://github.com/Sammyjo20/package-template

One of the biggest reasons I have stuck with Guzzle is because of its amazing feature list. You mentioned async requests but Guzzle comes with all the different options and the different stream wrappers are so useful - not to mention more complicated body types like multipart body are all supported. If we switched to the PSR sender being the primary one in v3 I would prefer if we matched the features that Guzzle had or better them (like making the internal codebase more modern, some of Guzzle still looks a bit old)

Then that goes on to my next part which is - why rebuild Guzzle? If we built it to match the same number of features, eventually we're just going to have something very similar to Guzzle. Perhaps I'm not seeing something here. This is the conversation I've had in my head a few times when I had considered making a PSR client. Again, maybe you don't need all the features of Guzzle but if we were to make it the primary driver of v3 we would need to make sure it doesn't regress in functionality for most people as I think Saloon being built on top of Guzzle is a big selling point for people.

One thing I do like though is that if we moved away from Guzzle, we could build our own standardised way to deal with sender config, headers, body and everything like that. Perhaps even Saloon can fill in on some of Guzzle's config so we don't have to implement it on every sender, like delay and of course request body.

There are definitely many pros and cons.

One final note to add - what are your thoughts on HTTPlug? Is this something that we should implement rather than PSR directly?

[aidan-casey]

but for the moment I would rather if the PSR sender was built as a separate library and then you can install the sender on a per-project basis when V3 comes around we can discuss moving the code into the core codebase or requiring the library in the main package and dropping Guzzle

I just realized I totally ignored this part in my response. 🙂

Totally understand that for v2. I think my proposal would be only basic support for PSR in the sender as v1 of the package, with some gradual support for things like multipart formatting by way of middleware as feature releases.

This could then get pulled back into the core package for v3 if that's the route you want to take.

[nikuscs]

Congratz @aidan-casey, this is the way indeed. Also while Laravel Http is nice but... its just a wrapper around a wrapper, so i dont really see a big point keeping it, unless you want to see some logs in Telescope.

[Sammyjo20]

Hey @aidan-casey

Apologies for the slow reply on this one. Your arguments are solid and I understand where you are coming from. I'm still struggling a little bit with the idea of having to basically rewrite Guzzle.

I do like however simplifying the codebase, moving to middleware completely but also decoupling Guzzle from Saloon but I think for the moment I can't justify completely uprooting Guzzle for version 3, maybe something for v4 but I'd be more than happy to have a PSR sender as a separate library that you could use if that satisfies your needs. That's only because I'm hoping v3 is going to be the next improvement for DX and I'd like as much if it being backwards compatible as possible. Just because it's the next major, doesn't mean we have to be slow in this.

That being said, on the contrary of my own statement we wouldn't have to rebuild everything, we would just have to rebuild:

• Body formatting
• Guzzle's config helpers

We may not need to rebuild

• Sending
• Response Streams
• Asynchronous Support (Because if a sender doesn't support it, we could throw an exception)

One part that really bugs me with Saloon is not being able to debug the PSR request to see the raw data being sent to servers - and if we had our own body formatting and everything like that we could do that.

My other question is around Guzzle's special features like the "stream", "sink" and "verify" options

I don't think we need "sink" but I love the stream option, as well as quite a few of Guzzle's other options - so how would they be implanted? Like with the verify option, is that a PHP cURL option?

I do believe there's a nicer way to build Guzzle's options though so that would be a good opportunity to do that 😀

So perhaps I need to really map it out - I do think it would future proof Saloon but we have to strike that balance of practicality and not rebuilding everything.

To wrap up, would you like to try starting with a PSR sender and with the coming weeks/months we could discuss how the new Saloon could look like? I'd love Saloon to live on for as long as it can and reach as many devs as it can and perhaps this is the next phase 🤠

[Sammyjo20]

Hey @aidan-casey I'm about to post something outside of this thread :)

[aidan-casey]

Apologies for the slow reply on this one.

No worries, @Sammyjo20! There are some pretty radical ideas being proposed here that impacts the future of the library, so totally understand the deliberation. 🙂

I'm still struggling a little bit with the idea of having to basically rewrite Guzzle.

I think the key thing to remember is that this truly makes it client agnostic as advertised by v2 (I would argue based on my points above this is not the case today). Think of it less about rewriting Guzzle and more about enabling simple PSR clients to be so much more affective by adding a robust set of API client features. 🙂

I can't justify completely uprooting Guzzle for version 3

Totally understand. If you are open to it, another option to propose here would be revising the Sender interface and just including two default senders: Psr18ClientSender and GuzzleSender. People relying heavily on these features can continue to use the Guzzle sender, while the core package begins to take a general direction of PSR + middleware.

contrary of my own statement we wouldn't have to rebuild everything
...
We may not need to rebuild
...
My other question is around Guzzle's special features like the "stream", "sink" and "verify" options

The first step here is probably figuring out a list of features that do need to be ported. I suspect a lot can remain untouched for the initial implementation as most users probably aren't tapping heavily into Guzzle.

In theory, middleware should be much quicker to develop out in the future than core package features. If someone reports missing functionality, that should be able to be addressed with relative ease.

To wrap up, would you like to try starting with a PSR sender and with the coming weeks/months we could discuss how the new Saloon could look like?

Definitely not opposed to this, but I do think it is worth having the conversation about how this gets implemented. If the package implementation will need to be significantly different from a core implementation, it may make sense to wait until that point.

[Sammyjo20]

Just a side note on this - I wonder if it's worth creating a Saloon Github Org so we can move the packages away from sammyjo20 namespace?

[juse-less]

I'd prefer that, at least. 🙂
It's easier to get a glimpse of Saloon-relevant projects.
Like.. project/repo list, updates by following the Saloon organisation over each individual project.

There's probably many other upsides, as well.

[aidan-casey]

Hands down, yes. 🙂

I might suggest a SaloonPHP or Saloon-PHP organization here on GitHub.

[Sammyjo20]

Hey @aidan-casey @juse-less

So I've been thinking about this whole PSR stuff and I think I've come up with something that could actually work really well, I'd love some feedback if you are happy to provide it.

So let's say for v3 we wanted to migrate away from "senders" and the coupling to Guzzle directly. This is how the flow could work.

1. Saloon Request 'Sent' --> 2. Goes to our PendingRequest --> 3. Runs our middleware --> 4. Convert a PendingRequest to a PSR-7 Request --> 5. PSR-7 request gets sent through PSR-18 client 6. We convert the PSR-7 response into a normal Saloon response

Here's a description of the flow

1. Normal Saloon Request as we have now
2. PendingRequest is a new class that has the same properties but acts as a temporary bridge so when we run middleware, we don't modify the original request class, we just modify the PendingRequest.
3. The saloon middleware pipeline is executed. This is responsible for building up the body, configuration options, creates fake responses, everything v2 does but even more. The PendingRequest should be pretty light
4. We now have a method in our PendingRequest class which converts it to a PSR-7 request. This is where we encode the body depending on the BodyRepository interface like we have currently in our Guzzle sender
5. No more sender, we just pass that request directly to the PSR-18 class.
6. Basically what we do now with the response $response::fromPsrResponse()

Also, where we have defaultSender on the connector, this would probably become resolveClient (or stay as sender) but must return the PSR-18 client. We then store this inside of a property on the connector like we do with sender, so it's executed once and kept for subsequent requests.

This is where people can apply Guzzle's config if they fancy, or even their own middleware. Like this:

protected function resolveClient(): Client
{
     $client = new Guzzle\Client([
           'timeout' => 60,
           'verify' => false, // Anything here
           'handler' => ... // Custom handler stack
     ]);

     return $client;
}

// Internally we'll do `$this->client ??= $this->resolveClient()`

Then Saloon's configuration variables could become class-based and sexy like this:

protected function defaultConfig(): array
{
      return [
              VerifyOption::create(false),
              StreamRessponse::create(),
      ];
}

Additionally, we could provide a hook on the request/connector to quickly change something with the PSR-7 request before it is sent.

public function handlePsrRequest(Request $request): Request
{
       $request->withHeaders();

       // ...

       return $request;
} 

Why keep PendingRequest?

So I'm thinking of keeping PendingRequest and not passing the PSR-7 request down the middleware pipeline because Saloon already has a beautiful, standardised way for handling headers, config, middleware, authentication - so I'd like to keep this and no matter what the PSR-18 client, Saloon's middleware is standardised.

This is like HTTP-Plug but on crack because it's

1. So so so much simplier
2. It has the power of Saloon, so class-based requests

Please tell me that after this you guys are as excited as I am about this potentially being a thing!

Also, kind of selfishly - if people were happy for me to, I'd quite like to do this rebuild? Something about it rewriting Saloon, kind of feels like it should come from me BUT I'm happy to take feedback and let us shape this together

[Sammyjo20]

The only other thing I'm thinking of is potentially keeping Sender as an interface but only have two methods on it's signature, this will allow us to better support send/sendAsync and throw and exceptions if a given PSR-18 interface doesn't support async

interface Sender
{
      public function send(ClientInterface $client, Request $request): PsrResponse
      {
             //
      }

      public function sendAsync(ClientInterface $client, Request $request): PsrResponse
      {
             //
      }
}

I know it's not as simple then as just dropping in a client, but it does allow us to have the flexibility to say "hey, we support async and if you provide a PSR-18 client that doesn't support async, we will throw an exception"

[aidan-casey]

Here's a description of the flow

Looks good to me, with the exception of removing the sender interface... more on that later.

Also, where we have defaultSender on the connector, this would probably become resolveClient (or stay as sender) but must return the PSR-18 client. We then store this inside of a property on the connector like we do with sender, so it's executed once and kept for subsequent requests.

I think this probably ends up becoming something like the following. This allows every piece of the PSR request to be configurable, but also automatically detects implementations if they are installed.

use Http\Discovery\Psr17FactoryDiscovery;
use Psr\Http\Client\ClientInterface;
use Psr\Http\Message\RequestFactoryInterface;
use Psr\Http\Message\StreamFactoryInterface;

protected function resolveClient(): ClientInterface
{
    return $this->client ??= Psr18ClientDiscovery::find();
}

protected function resolveRequestFactory(): RequestFactoryInterface
{
    return $this->requestFactory ??= Psr17FactoryDiscovery::findRequestFactory();
}

protected function resolveStreamFactory(): StreamFactoryInterface
{
    return $this->streamFactory ??= Psr17FactoryDiscovery::findStreamFactory();
}

Then Saloon's configuration variables could become class-based and sexy like this

Yep.

Additionally, we could provide a hook on the request/connector to quickly change something with the PSR-7 request before it is sent.

Or just force that upon middleware. 🙂

This is like HTTP-Plug but on crack

Totally get this and agree.

Please tell me that after this you guys are as excited as I am about this potentially being a thing!

Yes! 🎉

but it does allow us to have the flexibility to say "hey, we support async and if you provide a PSR-18 client that doesn't support async, we will throw an exception"

My recommendation would be to maintain the Sender interface, but in the following way:

interface Sender
{
      public function send(Request $request): PsrResponse
      {
             //
      }

      public function sendAsync(Request $request): Async
      {
             //
      }
}

class Psr18ClientSender implements Sender
{
      public function __construct(private readonly ClientInterface $client)
      {}

      public function send(Request $request): PsrResponse
      {
             return $this->client->sendRequest($request);
      }

      public function sendAsync(Request $request): Async
      {
             return new Async(fn () => $this->send($request));
      }
}

Async either becomes an in-house implementation, or better yet, a third party contract that can be brought in. Basically, you're not forcing the PSR-18 client to provide an async implementation, but senders basically become PSR-18 clients on crack. 😉

Also, kind of selfishly - if people were happy for me to, I'd quite like to do this rebuild? Something about it rewriting Saloon, kind of feels like it should come from me BUT I'm happy to take feedback and let us shape this together

Sure. Go for it. Just don't burn yourself out. 🙂

[Sammyjo20]

Hey @aidan-casey - thanks for the feedback. I totally agree with these points and agree with your interface proposal. I think this would be really good.

I'm going to continue with some planning over the next couple of days. There's still a couple of areas I'm a little anxious about which are.

• The Guzzle options that internally set cURL options. I wonder how we would pass those cURL options down to the sender
• How Guzzle handles streams. Text streams are fine, but what if you have a multipart stream with other streams inside of it like Guzzle supports.

I do keep going back and forth on "do I want to maintain all this extra code" but I do think it's a step in the right direction for Saloon. My only request is that we do it in an elegant way so that 95% of people who use Saloon with the default sender (Guzzle) are happy, but also people like yourselves can have a bit more control. Do you think doing this will open Saloon up to more users? (i.e is this the kind of thing that would hold some people back from adopting it?)

[Sammyjo20]

Just to keep this discussion open, I'm currently researching about HttpPlug and how Saloon could use it. It would save a considerable amount of development time to rebuild certain things like streams, body handling etc and would mean that Saloon isn't tied to a specific implementation. Like with all things, as Saloon is my baby I'm going to do plenty of research and testing on it before I consider using it - but it does look good so far!

[Sammyjo20]

Hey everyone, so just an update from me over here. I've been having a fun long weekend here learning about PSR-7, PSR-17 and PSR-18 and I have actually managed to throw together a working prototype of a Psr18Sender for Saloon 🥳 I toyed with using HTTPlug too, but I felt that it wasn't particularly difficult to use PSR-18 directly.

You can compare the changes I made here: v2...feature/psr-17-factories

While at a surface level, it didn't require much to be changed - underneath the hood, I'd like to make a few changes to Saloon to improve the way this will be integrated - there are a few places that are still quite guzzle-y which will need to be migrated, but then for v3 we can remove Guzzle as a dependency completely, and Saloon can be HTTP client-agnostic!

While I still believe that 90% of people using Saloon will want to continue using Guzzle, I think this is a great step forward because it'll allow Saloon to be free from implementation and be used by even more people. For those that will just want to get up and running, there will be a simple trait that they have to add to their connector like use GuzzleSender. For those that want to provide their own PSR-18 client, they can use the Psr18Sender where they have to pass in a PSR-17 request and stream factory, as well as the PSR-18 client. Then Saloon does the rest.

I've got a few things that I need to make sure I don't forget, all while wanting to keep Saloon's codebase as modern and tidy as possible. I'll keep this discussion updated, but here are some of the things I am thinking about:

Building Streams

We may need to require the multipart-stream-builder in order to build multipart Streams. The good news is that it requires a StreamFactory to be passed in.

• https://github.com/php-http/multipart-stream-builder

I don’t think it’s fair to install composer require php-http/multipart-stream-builder unless people actually want to use Multipart bodies. When they need it we could just push people to install it. If they’re using Guzzle - they won’t need it.

Providing Traits For DX

We could easily provide a use Guzzle trait in the connector to make it super-simple to just configure a connector to use Guzzle. I want it to be as friction-less as possible for people to just use Saloon as they like.

<?php

class SpotifyConnector extends Connector
{
	use Guzzle;
}

Better way to Customise Guzzle

When we switch to requiring a resolveSender method on the connector, we can suggest that if people want to use Guzzle middleware, they configure that inside of this method, rather than tapping into the sender later down the line and it getting confused with regular middleware. 🔥

protected function resolveSender(): Sender
{
    $sender = new GuzzleSender;
    
    $sender->guzzle->addMiddleware(...);
    
    return $sender;
}

Forcing an async implementation

We should install something like Guzzle’s Promise library to force a Promise implementation. This makes our life even easier. Guzzle’s promise library doesn’t have any dependencies and it is the most used library, so I think we should go for this

Building URI Interfaces instead of URLs

Guzzle has a handy query config option which can accept an array of query parameters. With PSR-18, we have to pass in a string or UriInterface, so we have to build our query parameters ourselves. We should consider how this should work. We need to remember that people could put query parameters in the URL but also in the query array store, so I might start building URI classes in the PendingRequest class.

New toStream method on all body repositories which requires a StreamFactory to be provided

This allows us to keep all of the logic of converting body repositories into a stream. We could also implement an interface and if that interface does not exist, we could throw an exception - this will help us if someone has made their own body repository.

Make sure we set the correct Content-Type based on the authenticator

Without Guzzle, Saloon doesn’t automatically set the content type for all the body repositories. We should have a sensible default that gets set in the boot method and that way if someone wants a different content type, we can let them overwrite it.

[aidan-casey]

@Sammyjo20 - Can this be a draft pull request so we can do some reviews? 🙂

[Sammyjo20]

@aidan-casey It's not quite ready to be a draft PR yet - I will go a bit further then make a draft PR when I have tests etc :)

[Sammyjo20]

I’ve been having another day of thinking and one thing I’m not a fan of is losing the ability to have configuration per-request for Guzzle, as well as the full asynchronous support that Guzzle provides so seamlessly.

I do also think that there aren’t many HTTP clients out there that people still use. I’m fairly certain that Guzzle is the main HTTP client people reach for, with the Symfony Client being second on that list. All this work for potentially no benefit because people just install Guzzle anyway, and the downside is it makes saloon more generic and harder to install.

Version 3 won’t come with Guzzle installed by default, BUT the GuzzleSender will be the default sender in Saloon’s core. This means for most people all you have to do is install Guzzle alongside Saloon and you’re done. Saloon can have Guzzle as a dev dependency to fully test this.

Saloon will also ship with a PSR-18 sender which is completely generic which you have to install separately. This allows us to have lots of tests for it. this allows people to use any PSR-18 sender and then they install the sender that they like. All they have to do is either add the trait to “use Psr18Sender” or extend the “resolveSender” method.

This provides us with the best of both worlds because Guzzle isn’t installed by default, but the simplest setup is just installing Guzzle.

I’ll also make sure that Saloon’s core becomes more generic, with the ability to create PSR-7 requests and use PSR factories but it’ll use the sender to discover where those PSR-17 factories are.

If you install the PSR-18 sender, then it will come with auto-discovery but you can provide all the factories separately you need.

Thoughts guys? @aidan-casey @juse-less

[Sammyjo20]

Sorry just had a sudden thought - I won’t bundle the GuzzleSender in Saloon’s core - I’ll have a GuzzleSender package so it can have its own versioning. So if Guzzle 8 comes along, all we have to do is tag another major version of the saloonhttp/guzzle-sender package

[Naoray]

Hello @Sammyjo20,

After reviewing the entire discussion, I'm curious about the decision not to develop a GuzzleSender package and eliminate the Guzzle dependency from Saloon.

I'm currently advocating for the adoption of Saloon to build an SDK for our product among my colleagues. However, one of our team members has encountered challenges with customers facing dependency issues related to Guzzle versions. Consequently, we are hesitant to rely on Guzzle or prefer to offer an alternative. If Saloon requires Guzzle during installation, it poses a challenge for us as we would still be susceptible to dependency issues. Could you share insights into this decision and let me know if this is final or if you are still considering moving guzzle outside of this package?

[Sammyjo20]

Hello @Naoray, thank you for your message.

I decided to continue using Guzzle for Saloon v3 and keep a direct dependency based on a few reasons. The biggest for me was realistic usage of Saloon. I've been building API integrations for over five years of my development career and I have always leaned towards Guzzle because of its popularity, stability and support so this was important to me. I understand that I may be naive to think that everyone else thinks the same, but its clear that a large portion of the PHP community uses Guzzle. For example, Laravel just has it installed within the core framework.

Another important reason why I decided to keep Guzzle in Saloon was to provide the most features and support. While Saloon v3 leans much more heavily on PSR-7 and PSR-17 and PSR-18 - Saloon still utilizes Guzzle's asynchronous logic and makes use of its powerful wrapper around cURL. Saloon's goal is to make Guzzle's development process simpler and provide a standardised structure.

Finally, another reason was developer experience. I want to make Saloon easy. It's goal is to get you to get that work done as fast as possible and not worry about the underlying dependencies or how HTTP requests are sent. I found that if the first step of installing Saloon was "decide what sender you're going to use" was going to be a blocker for some people, especially junior developers who are just trying to learn.

With all that being said - I think it would be good to discuss your concern a little more about dependencies because it's very fair. Guzzle 7 has been stable for 2.5 years, and when I asked the maintainers of Guzzle about Guzzle 8, they replied with "I am pretty happy with were Guzzle is at". So that gave me more confidence in keeping Guzzle. Unfortunately, when you introduce any open-source project, there's an added risk of any sub-dependencies creating a bug and causing issues. However, I can say from experience that I haven't had an issue with Guzzle 7 yet in using it myself directly or though Saloon.

If I were to extract Guzzle out of Saloon into a separate "Guzzle Sender" library, than if Guzzle 8 came along, you'd still have to manually upgrade to Guzzle 8 either by installing Saloon's "Guzzle 8 Sender" or by bumping the packages major version. This isn't much different to just upgrading the version of Saloon.

With Guzzle not being installed, there is an added benefit of not relying on a dependency, but again the trade-offs for me were not strong enough to risk the developer experience and the amazing level of functionality that you get by having Guzzle.

If you are able to share any more about your colleague's concerns around Guzzle, I'd love to know because I'm always taking notes for the next major version and I don't rule out any idea forever. If there's an edge I'm missing here, I'd absolutely love to know to help make Saloon better for everyone.

I hope this helps explain my justification. In summary, I'm extremely confident in Guzzle and I am very happy that Saloon is written using it, but I'm also very happy that v3 made it very easy to remove Guzzle in the future if I needed to, and for v4 I'm going to try and make it even easier.

[sandervanhooft]

Hey @Sammyjo20 ,

My colleague @Naoray asked me to chip in. I am still on the fence if Saloon is the way to go for us. It's a beaut for most cases but for high-transaction SDKs I prefer to have as little external dependencies as possible - but that's for a different discussion.

Happy to chip in here on the Guzzle dependency matter.

I totally get your reasoning here. That's exactly what I was thinking as well - at first.

Over the years I've encountered two major problems relying on a hard Guzzle dependency in our SDKs that made me reconsider.

The biggest issue
Some of our PHP SDKs get consumed by other plugins, in other frameworks and architectures totally beyond our control.

In some cases, this has resulted in the weirdest dependency hells. I am a big fan of using composer and strict SEMVER to manage all dependencies.

Then I learned that some popular frameworks actually don't work this way. 🙀

In WP/WooCommerce packages (enormous usage) for example it's not uncommon to include a hard copy of all dependencies in the package itself upon distribution.

Since Guzzle is so popular and relied on by many popular packages, we've had many runtime collisions because of this, sometimes even with multiple major Guzzle versions being present in one installation. Bad architecture and bad practices for sure, but the numbers and scale of adoption don't lie. It's just what's happening out there, and in these communities it's "business as usual" 🤷 .

We've tried working around this by providing a downloadable sdk zip on each release, using Scoper to make the release dependencies unique. To my taste, it was ugly, but for 99% of the dependency hell cases it did the trick.

The less obvious but potentially even bigger issue
We've encountered some significant issues in Guzzle itself that weren't properly addressed when questions were raised, suggestions were made or help was asked to guide us working on a PR to resolve it.

One issue in particular involves false positives/negatives on connection errors as detected by Guzzle. This means that on transactional calls (i.e. where money is involved), any retry logic based on connection issues should be treated as unreliable.

What we ended up doing
Like Saloon, we also were dealing with an existing audience, money and reputation on the line, lots of moving parts, didn't want to introduce any breaking changes. Also, there's just lots of Guzzle love going around.

Our thoughts:

• We wanted to get rid of the Guzzle dependency hell on some frameworks/architectures.
• We didn't want developers to have to think about the http client if they didn't want to.
• Guzzle is nice, mostly, so let's leverage it but don't depend on it. In most installations it's already available.
• We already had an injectable Guzzle Client
• Whatever we do: no breaking changes.

Result (as inspiration, not a suggestion. I might have taken a different route if we accepted a breaking change):

• Removed hard Guzzle dependency.
• Switched to an HttpAdapterInterface(which has the "send" method). The actual HttpAdapter implementation could be made PSR compliant, but doesn't have to be. This was mostly done to not introduce a breaking change.
• We detect if Guzzle is present, and what version. Then wire up and inject a matching HttpAdapter.
• As a fallback, we have included a default curl based HttpAdapter.
• For anyone that was overriding the default injectable Guzzle Client before, that still works. (no breaking change)
• We've dropped the downloadable ZIPs.

For reference: https://github.com/mollie/mollie-api-php/tree/f4f70abbe846de25dbcb40bcd84961b75825514c/src/HttpAdapter

Not trying to steer you in any way, just some experiences shared from the trenches.

[Sammyjo20]

Hey @sandervanhooft thank you for the time to reply to my message and to explain the reasons behind not using Saloon at this point in time. I totally understand where you are coming from. I have had some experience with Wordpress and I know that it can be a little bit like the wild-west (no pun intended), especially around plugins and dependencies.

At this point in time, I don't think I am ready to plan and maintain a version of Saloon which supports any HTTP client, however, if I were to do it, I would likely go with what you are suggesting and built a HTTP discovery feature into Saloon, very similar to how you wrote your Guzzle detection logic in your library.

I wish you the very best with your development projects, and congratulations on the wide adoption of your php-sdk, I saw that you have over 6 million downloads on Packagist, which is a wonderful achievement.