Re-add a PSR guide.

CHANGELOG.md

@@ -4,7 +4,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ## [Unreleased]
 ### Added
-- Added Guzzle and Symfony client factories.
+- Added Guzzle and Symfony client factories ([#287](https://github.com/opensearch-project/opensearch-php/pull/287))
 ### Changed
 ### Deprecated
 ### Removed
@@ -19,29 +19,28 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added workflow for automated API update using OpenSearch API specification ([#209](https://github.com/opensearch-project/opensearch-php/pull/209))
 - Added samples ([#218](https://github.com/opensearch-project/opensearch-php/pull/218))
 - Added support for PHP 8.3 and 8.4 ([#229](https://github.com/opensearch-project/opensearch-php/pull/229))
-- Added a Docker Compose config file for local development.
-- Added a test for the AWS signing client decorator
-- Added PHPStan Deprecation rules and baseline
-- Added PHPStan PHPUnit extensions and rules
-- Added Guzzle and Symfony HTTP client factories.
-- Added 'colinodell/psr-testlogger' as a dev dependency.
+- Added a Docker Compose config file for local development ([#245](https://github.com/opensearch-project/opensearch-php/pull/245))
+- Added a test for the AWS signing client decorator ([#252](https://github.com/opensearch-project/opensearch-php/pull/252))
+- Added PHPStan Deprecation rules and baseline ([#263](https://github.com/opensearch-project/opensearch-php/pull/263))
+- Added PHPStan PHPUnit extensions and rules ([#263](https://github.com/opensearch-project/opensearch-php/pull/263))
+- Added Guzzle and Symfony HTTP client factories ([#271](https://github.com/opensearch-project/opensearch-php/pull/271))
+- Added 'colinodell/psr-testlogger' as a dev dependency ([#271](https://github.com/opensearch-project/opensearch-php/pull/271))
 ### Changed
-- Switched to PSR Interfaces
-- Increased PHP min version to 8.1
-- Increased min version of `ezimuel/ringphp` to `^1.2.2`
-- Changed fluent setters to return static
+- Switched to PSR Interfaces ([#233](https://github.com/opensearch-project/opensearch-php/pull/233))
+- Increased PHP min version to 8.1 ([#233](https://github.com/opensearch-project/opensearch-php/pull/233))
+- Increased min version of `ezimuel/ringphp` to `^1.2.2` ([225](https://github.com/opensearch-project/opensearch-php/pull/225))
+- Changed fluent setters to return static ([#236](https://github.com/opensearch-project/opensearch-php/pull/236))
 ### Deprecated
 - Passing a callable to \OpenSearch\ClientBuilder::setEndpoint() is deprecated and replaced with passing an EndpointFactory to \OpenSearch\ClientBuilder::setEndpointFactory() ([#237](https://github.com/opensearch-project/opensearch-php/pull/237))
-- Connections, Connection pools and Selectors are deprecated. Use a PSR HTTP Client that supports retries instead.
-- Throwing exceptions for different HTTP status codes is deprecated. Use the response object to check the status code instead.
-- The following namespaces have been deprecated and will be removed in 3.0.0: 'async_search', 'searchable_snapshots', 'ssl', 'data_frame_transform_deprecated', 'monitoring'.
-- A number of exceptions under `\OpenSearch\Common\Exceptions` are deprecated and moved to `\OpenSearch\Exception`. 
+- Connections, Connection pools and Selectors are deprecated. Use a PSR HTTP Client that supports retries instead ([#245](https://github.com/opensearch-project/opensearch-php/pull/245))
+- The following namespaces have been deprecated and will be removed in 3.0.0: 'async_search', 'searchable_snapshots', 'ssl', 'data_frame_transform_deprecated', 'monitoring' ([#270](https://github.com/opensearch-project/opensearch-php/pull/270))
+- A number of exceptions under `\OpenSearch\Common\Exceptions` are deprecated and moved to `\OpenSearch\Exception` ([#274](https://github.com/opensearch-project/opensearch-php/pull/274))
 ### Removed
-- Removed support for PHP 7.3, 7.4 and 8.0.
-- Removed support for async requests which were never actually working.
+- Removed support for PHP 7.3, 7.4 and 8.0 ([#233](https://github.com/opensearch-project/opensearch-php/pull/233))
+- Removed support for async requests which were never actually working ([#233](https://github.com/opensearch-project/opensearch-php/pull/233))
 ### Fixed
-- Fixed PHP 8.4 deprecations
-- Fixed outdated tests
+- Fixed PHP 8.4 deprecations ([#229](https://github.com/opensearch-project/opensearch-php/pull/229))
+- Fixed outdated tests ([#245](https://github.com/opensearch-project/opensearch-php/pull/245))
 ### Updated APIs
 - Updated opensearch-php APIs to reflect [opensearch-api-specification@b9dcb25](https://github.com/opensearch-project/opensearch-api-specification/commit/b9dcb251d551e90ecfc416ba134efe83cbcbc1b3)
 - Updated opensearch-php APIs to reflect [opensearch-api-specification@9df46f8](https://github.com/opensearch-project/opensearch-api-specification/commit/9df46f8134641ae5b429e3e9269858c7cb27e4f0)

UPGRADING.md

@@ -1,14 +1,14 @@
 - [Upgrading OpenSearch PHP Client](#upgrading-opensearch-php-client)
-    - [Upgrading to >= 2.0.0](#upgrading-to--240)
-        - [HTTP Client Auto-Discovery](#http-client-auto-discovery)
-        - [Configuring Guzzle HTTP Client in 2.x](#configuring-guzzle-http-client-in-2x)
-        - [Configuring Symfony HTTP Client in 2.x](#configuring-symfony-http-client-in-2x)
+  - [Upgrading to \>= 2.4.0](#upgrading-to--240)
+    - [PSR-18 HTTP Client Interfaces](#psr-18-http-client-interfaces)
+    - [Configuring Guzzle HTTP Client in 2.4.x](#configuring-guzzle-http-client-in-24x)
+    - [Configuring Symfony HTTP Client in 2.4.x](#configuring-symfony-http-client-in-24x)
 
 # Upgrading OpenSearch PHP Client
 
 ## Upgrading to >= 2.4.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: 
+The openseach-php library 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-7/)
 - [PSR-17 HTTP Factories](https://www.php-fig.org/psr/psr-17/)
@@ -18,14 +18,13 @@ You can continue to use Guzzle, but will need to configure it as a PSR-18 HTTP C
 
 ### PSR-18 HTTP Client Interfaces
 
-Starting with `opensearch-php` 2.4.0 you can use any PSR-18 compatible HTTP client. 
+Starting with opensearch-php 2.4.0 you can use any PSR-18 compatible HTTP client. 
 
-To simplify creating a Client, we provide two factories to create PSR-18 HTTP clients
-for Guzzle and Symfony HTTP clients.
+To simplify creating a Client, we provide two factories to create PSR-18 HTTP clients for Guzzle and Symfony HTTP clients since opensearch-php 2.5.0.
 
 ### Configuring Guzzle HTTP Client in 2.4.x
 
-To configure Guzzle as a PSR HTTP Client with the similar configuration to opensearch 1.x you can use the following example:
+To configure Guzzle as a PSR HTTP Client with the similar configuration to opensearch-php 1.x you can use the following example:
 
 Ensure the Guzzle packages are installed via composer:
 
@@ -46,8 +45,7 @@ $info = $client->info();
 
 ### Configuring Symfony HTTP Client in 2.4.x
 
-You can configure [Symfony HTTP Client](https://symfony.com/doc/current/http_client.html) as a PSR HTTP Client using
-the following example:
+You can configure [Symfony HTTP Client](https://symfony.com/doc/current/http_client.html) as a PSR HTTP Client using the following example:
 
 ```php
 composer require symfony/http-client

USER_GUIDE.md

@@ -507,3 +507,4 @@ $client = \OpenSearch\ClientBuilder::fromConfig($config);
 * [Authentication](guides/auth.md)
 * [ML Commons](guides/ml-commons.md)
 * [Sending Raw JSON Requests](guides/raw-request.md)
+* [Using PSR Interfaces](guides/psr.md)

guides/psr.md

@@ -0,0 +1,91 @@
+- [Using PSR Interfaces](#using-psr-interfaces)
+  - [Configuring Guzzle HTTP Client](#configuring-guzzle-http-client)
+  - [Configuring Symfony HTTP Client](#configuring-symfony-http-client)
+
+# Using PSR Interfaces
+
+The opensearch-php client uses the following PSR interfaces: 
+
+- [PSR-7 HTTP message interfaces](https://www.php-fig.org/psr/psr-7/)
+- [PSR-17 HTTP Factories](https://www.php-fig.org/psr/psr-17/)
+- [PSR-18 HTTP Client](https://www.php-fig.org/psr/psr-18/)
+
+While it's recommended to use `OpenSearch\GuzzleClientFactory` and `OpenSearch\SymfonyClientFactory`, you can have more control over the construction of the client as described below.
+
+## Configuring Guzzle HTTP Client
+
+To configure [Guzzle](https://docs.guzzlephp.org/en/stable/) as a PSR HTTP Client 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)', \OpenSearch\Client::VERSION, PHP_OS, PHP_VERSION),
+    ]
+]);
+
+$guzzleHttpFactory = new \GuzzleHttp\Psr7\HttpFactory();
+
+$serializer = new \OpenSearch\Serializers\SmartSerializer();
+
+$requestFactory = new \OpenSearch\RequestFactory(
+    $guzzleHttpFactory,
+    $guzzleHttpFactory,
+    $guzzleHttpFactory,
+    $serializer,
+);
+
+$transport = (new OpenSearch\TransportFactory())
+    ->setHttpClient($guzzleClient)
+    ->setRequestFactory($requestFactory)
+    ->create();
+
+$endpointFactory = new \OpenSearch\EndpointFactory();
+$client = new \OpenSearch\Client($transport, $endpointFactory, []);
+
+// Send a request to the 'info' endpoint.
+$info = $client->info();
+```
+
+## Configuring Symfony HTTP Client
+
+To 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',
+    ],
+]);
+
+$serializer = new \OpenSearch\Serializers\SmartSerializer();
+
+$requestFactory = new \OpenSearch\RequestFactory(
+    $symfonyPsr18Client,
+    $symfonyPsr18Client,
+    $symfonyPsr18Client,
+    $serializer,
+);
+
+$transport = (new \OpenSearch\TransportFactory())
+    ->setHttpClient($symfonyPsr18Client)
+    ->setRequestFactory($requestFactory)
+    ->create();
+
+$endpointFactory = new \OpenSearch\EndpointFactory();
+$client = new \OpenSearch\Client($transport, $endpointFactory, []);
+
+// Send a request to the 'info' endpoint.
+$info = $client->info();
+
+```

src/OpenSearch/Client.php

@@ -108,7 +108,7 @@
  */
 class Client
 {
-    public const VERSION = '2.4.1';
+    public const VERSION = '2.5.0';
 
     /**
      * @var Transport

util/template/client-class

@@ -34,7 +34,7 @@ use OpenSearch\Namespaces\NamespaceBuilderInterface;
 class Client
 {
 
-    const VERSION = '2.4.1';
+    const VERSION = '2.5.0';
 
     /**
      * @var Transport