From a67354bcf6e1c11f3c79bf5b52968a497b4eeab4 Mon Sep 17 00:00:00 2001
From: Kim Pepper <kim@pepper.id.au>
Date: Tue, 17 Dec 2024 10:21:02 +1100
Subject: [PATCH] Adds UPGRADING doc

Signed-off-by: Kim Pepper <kim@pepper.id.au>
---
 UPGRADING.md      | 90 +++++++++++++++++++++++++++++++++++++++++++++++
 samples/index.php | 12 +++++++
 2 files changed, 102 insertions(+)
 create mode 100644 UPGRADING.md

diff --git a/UPGRADING.md b/UPGRADING.md
new file mode 100644
index 00000000..5e818ccf
--- /dev/null
+++ b/UPGRADING.md
@@ -0,0 +1,90 @@
+- [Upgrading OpenSearch PHP Client](#upgrading-opensearch-php-client)
+    - [Upgrading to >= 2.0.0](#upgrading-to->=-2.0.0)
+        - [HTTP Client Auto-Discovery](#http-client-auto-discovery)
+        - [Configuring Guzzle HTTP Client in 2.x](#configuring-guzzle-http-client-in-2.x)
+        - [Configuring Symfony HTTP Client in 2.x](#configuring-symfony-http-client-in-2.x)
+
+# Upgrading OpenSearch PHP Client
+
+## Upgrading to >= 2.0.0
+
+openseach-php removes the hard-coded dependency on the [Guzzle HTTP client](https://docs.guzzlephp.org/en/stable/#) and switches to the following PSR interfaces: 
+
+- [PSR-7 HTTP message interfaces](https://www.php-fig.org/psr/psr-17/)
+- [PSR-17 HTTP Factories](https://www.php-fig.org/psr/psr-17/)
+- [PSR-18 HTTP Client](https://www.php-fig.org/psr/psr-18/)
+
+You can continue to use Guzzle, but will need to configure it as a PSR-18 HTTP Client.
+
+### HTTP Client Auto-Discovery
+
+opensearch-php 2.x will try and discover and install a PSR HTTP Client using [PHP-HTTP Discovery](https://docs.php-http.org/en/latest/discovery.html) 
+if one is not explicitly provided.
+
+```php
+$transport = (new \OpenSearch\TransportFactory())->create();
+$endpointFactory = new \OpenSearch\EndpointFactory();
+$client = new Client($transport, $endpointFactory, []);
+
+// Send a request to the 'info' endpoint.
+$info = $client->info();
+```
+
+### Configuring Guzzle HTTP Client in 2.x
+
+To configure Guzzle as a PSR HTTP Client with the similar configuration to opensearch 1.x you can use the following example:
+
+```php
+$guzzleClient = new \GuzzleHttp\Client([
+    'base_uri' => 'https://localhost:9200',
+    'auth' => ['admin', getenv('OPENSEARCH_PASSWORD')],
+    'verify' => false,
+    'retries' => 2,
+    'headers' => [
+        'Accept' => 'application/json',
+        'Content-Type' => 'application/json',
+        'User-Agent' => sprintf('opensearch-php/%s (%s; PHP %s)', Client::VERSION, PHP_OS, PHP_VERSION),
+    ]
+]);
+$guzzleHttpFactory = new \GuzzleHttp\Psr7\HttpFactory();
+$transport = (new OpenSearch\TransportFactory())
+    ->setHttpClient($guzzleClient)
+    ->setPsrRequestFactory($guzzleHttpFactory)
+    ->setStreamFactory($guzzleHttpFactory)
+    ->setUriFactory($guzzleHttpFactory)
+    ->create();
+
+$endpointFactory = new \OpenSearch\EndpointFactory();
+$client = new Client($transport, $endpointFactory, []);
+```
+
+### Configuring Symfony HTTP Client in 2.x
+
+You can configure [Symfony HTTP Client](https://symfony.com/doc/current/http_client.html) as a PSR HTTP Client using
+the following example:
+
+```php
+$symfonyPsr18Client = (new \Symfony\Component\HttpClient\Psr18Client())->withOptions([
+    'base_uri' => 'https://localhost:9200',
+    'auth_basic' => ['admin', getenv('OPENSEARCH_PASSWORD')],
+    'verify_peer' => false,
+    'max_retries' => 2,
+    'headers' => [
+        'Accept' => 'application/json',
+        'Content-Type' => 'application/json',
+    ],
+]);
+
+$transport = (new OpenSearch\TransportFactory())
+    ->setHttpClient($symfonyPsr18Client)
+    ->setPsrRequestFactory($symfonyPsr18Client)
+    ->setStreamFactory($symfonyPsr18Client)
+    ->setUriFactory($symfonyPsr18Client)
+    ->create();
+
+$client = new Client($transport, $endpointFactory, []);
+
+// Send a request to the 'info' endpoint.
+$info = $client->info();
+
+```
diff --git a/samples/index.php b/samples/index.php
index 2f98bcd3..fb8a5706 100644
--- a/samples/index.php
+++ b/samples/index.php
@@ -9,6 +9,16 @@
 
 require_once __DIR__ . '/vendor/autoload.php';
 
+
+// Auto-configure by discovery example
+
+$transport = (new \OpenSearch\TransportFactory())->create();
+$endpointFactory = new \OpenSearch\EndpointFactory();
+$client = new Client($transport, $endpointFactory, []);
+
+// Send a request to the 'info' endpoint.
+$info = $client->info();
+
 // Guzzle example
 
 $guzzleClient = new \GuzzleHttp\Client([
@@ -33,6 +43,7 @@
 $endpointFactory = new \OpenSearch\EndpointFactory();
 $client = new Client($transport, $endpointFactory, []);
 
+// Send a request to the 'info' endpoint.
 $info = $client->info();
 
 
@@ -59,4 +70,5 @@
 
 $client = new Client($transport, $endpointFactory, []);
 
+// Send a request to the 'info' endpoint.
 $info = $client->info();