From 14181faf3f728754d19a5739227f089cab32528c Mon Sep 17 00:00:00 2001
From: Kim Pepper <kim@pepper.id.au>
Date: Thu, 13 Feb 2025 08:42:37 +1100
Subject: [PATCH] Update user guide with new factory approach (#291)

* Update user guide with new factory approach

Signed-off-by: Kim Pepper <kim@pepper.id.au>

* Update USER_GUIDE.md

Co-authored-by: Shyim <github@shyim.de>
Signed-off-by: Kim Pepper <kim@pepper.id.au>

* Update USER_GUIDE.md

Co-authored-by: Daniel (dB.) Doubrovkine <dblock@dblock.org>
Signed-off-by: Kim Pepper <kim@pepper.id.au>

* Address feedback

Signed-off-by: Kim Pepper <kim@pepper.id.au>

---------

Signed-off-by: Kim Pepper <kim@pepper.id.au>
Co-authored-by: Shyim <github@shyim.de>
Co-authored-by: Daniel (dB.) Doubrovkine <dblock@dblock.org>
---
 USER_GUIDE.md | 97 +++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 79 insertions(+), 18 deletions(-)

diff --git a/USER_GUIDE.md b/USER_GUIDE.md
index 0d7141bc..10a80406 100644
--- a/USER_GUIDE.md
+++ b/USER_GUIDE.md
@@ -1,8 +1,27 @@
 - [User Guide](#user-guide)
   - [Example usage](#example-usage)
+  - [Client Factories](#client-factories)
+    - [Guzzle Client Factory](#guzzle-client-factory)
+    - [Symfony Client Factory](#symfony-client-factory)
+  - [ClientBuilder (Deprecated)](#clientbuilder-deprecated)
+  - [Advanced Features](#advanced-features)
+
 # User Guide
 
-Install this client using Composer into your project `composer req opensearch-project/opensearch-php`
+Install this client using Composer into your project 
+```bash
+composer require opensearch-project/opensearch-php
+```
+
+Install a PSR-18 compatible HTTP client. For example, to use Guzzle:
+```bash
+composer require guzzlehttp/guzzle
+```
+
+Alternatively, you can use Symfony:
+```bash
+composer require symfony/http-client
+```
 
 ## Example usage
 
@@ -25,23 +44,11 @@ class MyOpenSearchClass
     public function __construct()
     {
         // Simple Setup
-        $this->client = OpenSearch\ClientBuilder::fromConfig([
-            'hosts' => [
-                'https://localhost:9200'
-            ],
-            'retries' => 2,
-            'handler' => OpenSearch\ClientBuilder::multiHandler()
+        $this->client = (new \OpenSearch\GuzzleClientFactory())->create([
+            'base_uri' => 'https://localhost:9200',
+            'auth' => ['admin', getenv('OPENSEARCH_PASSWORD')],
+            'verify' => false, // Disables SSL verification for local development.
         ]);
-
-        // OR via Builder
-        // $this->client = (new \OpenSearch\ClientBuilder())
-        //     ->setHosts(['https://localhost:9200'])
-        //     ->setBasicAuthentication('admin', 'admin') // For testing only. Don't store credentials in code.
-        //     // or, if using AWS SigV4 authentication:
-        //     ->setSigV4Region('us-east-2')
-        //     ->setSigV4CredentialProvider(true)
-        //     ->setSSLVerification(false) // For testing only. Use certificate for validation
-        //     ->build();
     }
 
 
@@ -359,7 +366,61 @@ try {
 
 ```
 
-## ClientBuilder
+## Client Factories
+
+You can create an OpenSearch Client using any [PSR-18](https://www.php-fig.org/psr/psr-18/) compatible HTTP client. Two factories are provided to reduce the boilerplate code required to create a client using [Guzzle](https://docs.guzzlephp.org/en/stable/) or [Symfony](https://symfony.com/doc/current/http_client.html) HTTP clients.
+
+The `GuzzleClientFactory` and `SymfonyClientFactory` classes are used to create an OpenSearch Client instance.
+
+### Guzzle Client Factory
+
+This factory creates an OpenSearch Client instance using the Guzzle HTTP client.
+
+```bash
+composer require guzzlehttp/guzzle
+```
+
+```php
+$client = (new \OpenSearch\GuzzleClientFactory())->create([
+    'base_uri' => 'https://localhost:9200',
+    'auth' => ['admin', getenv('OPENSEARCH_PASSWORD')],
+    'verify' => false,
+]);
+```
+`GuzzleClientFactory::__construct()` accepts an `int $maxRetries` as the first argument to enable retrying a request
+when a `500 Server Error` status code is received in the response, or network connection error occurs. A PSR-3 Logger
+can be passed as the second argument to log the retries.
+
+[Guzzle Request options](https://docs.guzzlephp.org/en/stable/request-options.html) can be passed to the 
+`create()` method. The `base_uri` option is *required*.
+
+### Symfony Client Factory
+
+This factory creates an OpenSearch Client instance using the Symfony HTTP client.
+
+```bash
+composer require symfony/http-client
+```
+
+```php
+$client = (new \OpenSearch\SymfonyClientFactory())->create([
+    'base_uri' => 'https://localhost:9200',
+    'auth_basic' => ['admin', getenv('OPENSEARCH_PASSWORD')],
+    'verify_peer' => false,
+]);
+````
+
+The `SymfonyClientFactory` constructor accepts an `int $maxRetries` as the first argument to enable retrying a request
+when a `500 Server Error` status code is received in the response, or network connection error occurs. A PSR-3 Logger
+can be passed as the second argument to log the retries.
+
+[Symfony HTTP Client configuration options](https://symfony.com/doc/current/http_client.html#configuration-options) can 
+be passed to the `create()` method. The `base_uri` option is *required*.
+
+## ClientBuilder (Deprecated)
+
+**`ClientBuilder` is deprecated in 2.4.0 and will be removed in 3.0.0. Use the `GuzzleClientFactory` or `SymfonyClientFactory` instead.**
+
 
 The `\OpenSearch\ClientBuilder` class is used to create a `\OpenSearch\Client` instance. It provides a fluent interface for configuring the client.