From 6c8d1bebb93339b1d0439400cb7ad976e1364f68 Mon Sep 17 00:00:00 2001 From: dblock Date: Thu, 6 Feb 2025 07:35:53 -0500 Subject: [PATCH] Re-add a PSR guide. Signed-off-by: dblock --- CHANGELOG.md | 37 ++++++++-------- UPGRADING.md | 20 ++++----- USER_GUIDE.md | 1 + guides/psr.md | 91 ++++++++++++++++++++++++++++++++++++++ src/OpenSearch/Client.php | 2 +- util/template/client-class | 2 +- 6 files changed, 121 insertions(+), 32 deletions(-) create mode 100644 guides/psr.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 530f5ae7e..fccf9c3dc 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/UPGRADING.md b/UPGRADING.md index f16f73be7..adf80cc8d 100644 --- a/UPGRADING.md +++ b/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 diff --git a/USER_GUIDE.md b/USER_GUIDE.md index e37a2a18c..0d7141bcd 100644 --- a/USER_GUIDE.md +++ b/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) diff --git a/guides/psr.md b/guides/psr.md new file mode 100644 index 000000000..7ad01b194 --- /dev/null +++ b/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(); + +``` diff --git a/src/OpenSearch/Client.php b/src/OpenSearch/Client.php index 5334b5fbd..031ab6d55 100644 --- a/src/OpenSearch/Client.php +++ b/src/OpenSearch/Client.php @@ -108,7 +108,7 @@ */ class Client { - public const VERSION = '2.4.1'; + public const VERSION = '2.5.0'; /** * @var Transport diff --git a/util/template/client-class b/util/template/client-class index eef11ad31..40477da2c 100644 --- a/util/template/client-class +++ b/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