From f70c97af2f4141c3ed715d33df344153f86139ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Fri, 23 Feb 2024 10:35:10 +0100 Subject: [PATCH 1/2] [DOCS] Adds section about version compatibility to overview. (#1394) --- README.md | 19 +++++++++++++++++++ docs/overview.asciidoc | 25 +++++++++++++++++++++++++ 2 files changed, 44 insertions(+) diff --git a/README.md b/README.md index 7ea3e7e6b..117239386 100644 --- a/README.md +++ b/README.md @@ -64,6 +64,25 @@ the major version of the corresponding Enterprise Search implementation. For example, for Elasticsearch `7.16`, use `7.16` of this library or above, but not `8.0`. +## Compatibility + +The Elasticsearch client is compatible with currently maintained PHP versions. + +Language clients are forward compatible; meaning that clients support +communicating with greater or equal minor versions of Elasticsearch without +breaking. It does not mean that the client automatically supports new features +of newer Elasticsearch versions; it is only possible after a release of a new +client version. For example, a 8.12 client version won't automatically support +the new features of the 8.13 version of Elasticsearch, the 8.13 client version +is required for that. Elasticsearch language clients are only backwards +compatible with default distributions and without guarantees made. + +| Elasticsearch Version | Elasticsearch-PHP Branch | Supported | +| --------------------- | ------------------------ | --------- | +| main | main | | +| 8.x | 8.x | 8.x | +| 7.x | 7.x | 7.17 | + ## Backward Incompatible Changes :boom: The 8.0.0 version of `elasticsearch-php` contains a new implementation compared diff --git a/docs/overview.asciidoc b/docs/overview.asciidoc index 9d1881170..cc03742c0 100644 --- a/docs/overview.asciidoc +++ b/docs/overview.asciidoc @@ -24,6 +24,31 @@ standard is a community effort that contains a set of interfaces defined by the PHP Framework Interop Group. For more information, refer to the https://www.php-fig.org/psr/psr-7/[PSR 7 standard documentation]. + +[discrete] +[[version-compatibility]] +=== {es} and PHP version Compatibility + +The {es} client is compatible with currently maintained PHP versions. + +Language clients are forward compatible; meaning that clients support +communicating with greater or equal minor versions of {es} without breaking. It +does not mean that the client automatically supports new features of newer {es} +versions; it is only possible after a release of a new client version. For +example, a 8.12 client version won't automatically support the new features of +the 8.13 version of {es}, the 8.13 client version is required for that. +{es} language clients are only backwards compatible with default distributions +and without guarantees made. + +|=== +| Elasticsearch Version | Elasticsearch-PHP Branch | Supported + +| main | main | +| 8.x | 8.x | 8.x +| 7.x | 7.x | 7.17 +|=== + + * <> include::breaking-changes.asciidoc[] \ No newline at end of file From acade92de444944a5a481976876b61431a6ef9fe Mon Sep 17 00:00:00 2001 From: Enrico Zimuel Date: Tue, 26 Mar 2024 09:12:06 +0100 Subject: [PATCH 2/2] Added mapTo feature, see #1398 (#1399) * Added mapTo feature, see #1398 * Fixed php-http/message-factory issue and extended memory to 256M for phpstan --- composer.json | 7 ++- src/Response/Elasticsearch.php | 62 ++++++++++++++++++++ src/Utility.php | 14 +++++ tests/Response/ElasticsearchTest.php | 84 +++++++++++++++++++++++++++- tests/Response/TestMapClass.php | 24 ++++++++ 5 files changed, 187 insertions(+), 4 deletions(-) create mode 100644 tests/Response/TestMapClass.php diff --git a/composer.json b/composer.json index 2e7d30b68..50c5c1838 100644 --- a/composer.json +++ b/composer.json @@ -26,8 +26,9 @@ "symfony/finder": "~4.0", "nyholm/psr7": "^1.5", "php-http/mock-client": "^1.5", - "symfony/http-client": "^5.0|^6.0", - "psr/http-factory" : "^1.0" + "symfony/http-client": "^5.0|^6.0|^7.0", + "psr/http-factory" : "^1.0", + "php-http/message-factory" : "^1.0" }, "autoload": { "psr-4": { @@ -51,7 +52,7 @@ "vendor/bin/phpunit --testdox -c phpunit-integration-cloud-tests.xml" ], "phpstan": [ - "phpstan analyse src --level 2 --no-progress" + "phpstan analyse src --level 2 --no-progress --memory-limit 256M" ] }, "config": { diff --git a/src/Response/Elasticsearch.php b/src/Response/Elasticsearch.php index 164d999fa..267f72b12 100644 --- a/src/Response/Elasticsearch.php +++ b/src/Response/Elasticsearch.php @@ -15,17 +15,20 @@ namespace Elastic\Elasticsearch\Response; use ArrayAccess; +use DateTime; use Elastic\Elasticsearch\Exception\ArrayAccessException; use Elastic\Elasticsearch\Exception\ClientResponseException; use Elastic\Elasticsearch\Exception\ServerResponseException; use Elastic\Elasticsearch\Traits\MessageResponseTrait; use Elastic\Elasticsearch\Traits\ProductCheckTrait; +use Elastic\Elasticsearch\Utility; use Elastic\Transport\Exception\UnknownContentTypeException; use Elastic\Transport\Serializer\CsvSerializer; use Elastic\Transport\Serializer\JsonSerializer; use Elastic\Transport\Serializer\NDJsonSerializer; use Elastic\Transport\Serializer\XmlSerializer; use Psr\Http\Message\ResponseInterface; +use stdClass; /** * Wraps a PSR-7 ResponseInterface offering helpers to deserialize the body response @@ -224,4 +227,63 @@ public function offsetUnset($offset): void { throw new ArrayAccessException('The array is reading only'); } + + /** + * Map the response body to an object of a specific class + * by default the class is the PHP standard one (stdClass) + * + * This mapping works only for ES|QL results (with columns and values) + * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/esql.html + * + * @return object[] + */ + public function mapTo(string $class = stdClass::class): array + { + $response = $this->asArray(); + if (!isset($response['columns']) || !isset($response['values'])) { + throw new UnknownContentTypeException(sprintf( + "The response is not a valid ES|QL result. I cannot mapTo(\"%s\")", + $class + )); + } + $iterator = []; + $ncol = count($response['columns']); + foreach ($response['values'] as $value) { + $obj = new $class; + for ($i=0; $i < $ncol; $i++) { + $field = Utility::formatVariableName($response['columns'][$i]['name']); + if ($class !== stdClass::class && !property_exists($obj, $field)) { + continue; + } + switch($response['columns'][$i]['type']) { + case 'boolean': + $obj->{$field} = (bool) $value[$i]; + break; + case 'date': + $obj->{$field} = new DateTime($value[$i]); + break; + case 'alias': + case 'text': + case 'keyword': + case 'ip': + $obj->{$field} = (string) $value[$i]; + break; + case 'integer': + $obj->{$field} = (int) $value[$i]; + break; + case 'long': + case 'double': + $obj->{$field} = (float) $value[$i]; + break; + case 'null': + $obj->{$field} = null; + break; + default: + $obj->{$field} = $value[$i]; + } + } + $iterator[] = $obj; + } + return $iterator; + } } \ No newline at end of file diff --git a/src/Utility.php b/src/Utility.php index 0bc8593e1..d54185ce5 100644 --- a/src/Utility.php +++ b/src/Utility.php @@ -45,4 +45,18 @@ public static function urlencode(string $url): string ? urlencode($url) : rawurlencode($url); } + + /** + * Remove all the characters not valid for a PHP variable name + * The valid characters are: a-z, A-Z, 0-9 and _ (underscore) + * The variable name CANNOT start with a number + */ + public static function formatVariableName(string $var): string + { + // If the first character is a digit, we append the underscore + if (is_int($var[0])) { + $var = '_' . $var; + } + return preg_replace('/[^a-zA-Z0-9_]/', '', $var); + } } \ No newline at end of file diff --git a/tests/Response/ElasticsearchTest.php b/tests/Response/ElasticsearchTest.php index 8e5f0fbee..1a3e30827 100644 --- a/tests/Response/ElasticsearchTest.php +++ b/tests/Response/ElasticsearchTest.php @@ -14,15 +14,17 @@ namespace Elastic\Elasticsearch\Tests\Response; +use DateTime; use Elastic\Elasticsearch\Exception\ArrayAccessException; use Elastic\Elasticsearch\Exception\ClientResponseException; use Elastic\Elasticsearch\Exception\ProductCheckException; use Elastic\Elasticsearch\Exception\ServerResponseException; use Elastic\Elasticsearch\Response\Elasticsearch; +use Elastic\Transport\Exception\UnknownContentTypeException; use Nyholm\Psr7\Factory\Psr17Factory; use PHPUnit\Framework\TestCase; use Psr\Http\Message\ResponseInterface; - +use stdClass; class ElasticsearchTest extends TestCase { protected Psr17Factory $psr17Factory; @@ -215,4 +217,84 @@ public function testWithStatusForPsr7Version1And2Compatibility() $this->elasticsearch = $this->elasticsearch->withStatus(400); $this->assertEquals(400, $this->elasticsearch->getStatusCode()); } + + public function testMapToStdClassAsDefault() + { + $array = [ + 'columns' => [ + ['name' => 'a', 'type' => 'integer'], + ['name' => 'b', 'type' => 'date'] + ], + 'values' => [ + [1, '2023-10-23T12:15:03.360Z'], + [3, '2023-10-23T13:55:01.543Z'] + ] + ]; + $body = $this->psr17Factory->createStream(json_encode($array)); + $this->elasticsearch->setResponse($this->response200->withBody($body)); + + $iterator = $this->elasticsearch->mapTo(); + $this->assertIsArray($iterator); + $this->assertEquals(stdClass::class, get_class($iterator[0])); + $this->assertEquals(stdClass::class, get_class($iterator[1])); + $this->assertEquals('integer', gettype($iterator[0]->a)); + $this->assertEquals(DateTime::class, get_class($iterator[0]->b)); + $this->assertEquals('integer', gettype($iterator[1]->a)); + $this->assertEquals(DateTime::class, get_class($iterator[1]->b)); + } + + public function testMapToStdClass() + { + $array = [ + 'columns' => [ + ['name' => 'a', 'type' => 'integer'], + ['name' => 'b', 'type' => 'date'] + ], + 'values' => [ + [1, '2023-10-23T12:15:03.360Z'], + [3, '2023-10-23T13:55:01.543Z'] + ] + ]; + $body = $this->psr17Factory->createStream(json_encode($array)); + $this->elasticsearch->setResponse($this->response200->withBody($body)); + + $iterator = $this->elasticsearch->mapTo(stdClass::class); + $this->assertIsArray($iterator); + $this->assertEquals(stdClass::class, get_class($iterator[0])); + $this->assertEquals(stdClass::class, get_class($iterator[1])); + } + + public function testMapToWithoutEsqlResponseWillThrowException() + { + $array = ['foo' => 'bar']; + $body = $this->psr17Factory->createStream(json_encode($array)); + $this->elasticsearch->setResponse($this->response200->withBody($body)); + + $this->expectException(UnknownContentTypeException::class); + $iterator = $this->elasticsearch->mapTo(); + } + + public function testMapToCustomClass() + { + $array = [ + 'columns' => [ + ['name' => 'a', 'type' => 'integer'], + ['name' => 'b', 'type' => 'date'] + ], + 'values' => [ + [1, '2023-10-23T12:15:03.360Z'], + [3, '2023-10-23T13:55:01.543Z'] + ] + ]; + $body = $this->psr17Factory->createStream(json_encode($array)); + $this->elasticsearch->setResponse($this->response200->withBody($body)); + + $iterator = $this->elasticsearch->mapTo(TestMapClass::class); + + $this->assertIsArray($iterator); + $this->assertEquals(TestMapClass::class, get_class($iterator[0])); + $this->assertEquals('integer', gettype($iterator[0]->a)); + $this->assertEquals(DateTime::class, get_class($iterator[0]->b)); + $this->assertEquals('', $iterator[0]->c); + } } \ No newline at end of file diff --git a/tests/Response/TestMapClass.php b/tests/Response/TestMapClass.php new file mode 100644 index 000000000..e319ac71c --- /dev/null +++ b/tests/Response/TestMapClass.php @@ -0,0 +1,24 @@ +