[PROPOSAL] Un-deprecate the builder pattern

[dblock]

What/Why

What are you proposing?

With the PSR work we deprecated the builder pattern.

https://github.com/opensearch-project/opensearch-php/blob/main/src/OpenSearch/ClientBuilder.php#L48

Do we have to? From the user perspective it seems easier to use and automatically detects the available Psr library. So why deprecate it? What are the downsides of the builder pattern? From the upsides I see less code to write to accomplish the same thing.

What users have asked for this feature?

Users that like to write less code.

What problems are you trying to solve?

Give users a way to use the client simply.

Any remaining open questions?

Would love to hear from @kimpepper on this topic before we release 2.4.0 via #244.

[kimpepper]

The current builder is there to support the legacy ringphp connection approach. If we un-deprecate it, we would not be able to remove ringphp in 3.x.

We could create separate builders for Guzzle and Symfony HTTP client which would reduce the amount of boilerplate.

[dblock]

Ok, I think I am proposing the latter. We can definitely do this later.

[kimpepper]

Created #271 to simplify creating the http clients.

[kimpepper]

I think using the auto-discovery approach is still the simplest:

$transport = (new \OpenSearch\TransportFactory())->create();
$endpointFactory = new \OpenSearch\EndpointFactory();
$client = new \OpenSearch\Client($transport, $endpointFactory, []);

[dblock]

I think #271 is mostly solving this, and we just need docs? @kimpepper ?

[kimpepper]

Yeah some doc updates are still needed.

[kimpepper]

I added #287 which takes us back to almost exactly the same API as the deprecated ClientBuilder::build() approach.

[dblock]

@kimpepper So should we be recommending these factories as the default construction or what we have in https://github.com/opensearch-project/opensearch-php/blob/main/USER_GUIDE.md? Want to do a pass on that doc and we can close this issue after that's done?

[kimpepper]

I created #291 to update the user guide.

[derikb]

Was updating to 2.4 and saw the deprecation notice about ClientBuilder... and I'm super confused about how to replace it. The PR for updating the docs provides some minimal advice but doesn't at all address how the auth should work now for AWS credentials.

[dblock]

@derikb Take a look at dblock/opensearch-php-client-demo#1, there's working code for guzzle and symfony. I had also updated https://github.com/opensearch-project/opensearch-php/blob/main/guides/auth.md.

I think we need to do a better job here. The UPGRADING guide needs to talk about this path, auth.md needs to remove deprecated code examples, and we need to support SigV4 on top of #287 in 2.5.0 (cc: @kimpepper). @derikb maybe once you sort it out for your application you can help at least with the UPGRADING.md part?

[derikb]

Thanks @dblock I'll take a look and see what I can get working.

[derikb]

oh and fwiw I totally missed the link to the auth guide way down there at the bottom of the user guide.

[dblock]

oh and fwiw I totally missed the link to the auth guide way down there at the bottom of the user guide.

Maybe surface it in the README better?