Merge branch 'master' into php.standard

Author: szabosteve

.ci/Dockerfile

@@ -34,7 +34,4 @@ RUN composer install
 
 COPY . .
 
-# Updating elasticsearch submodule
-RUN git submodule update --init --recursive
-
 CMD ["bash", ".ci/yaml-tests.sh"]

docs/breaking-changes.asciidoc

@@ -1,8 +1,8 @@
 [[breaking_changes]]
-== Breaking changes from 6.x
+=== Breaking changes from 6.x
 
 [discrete]
-=== E_USER_DEPRECATED notice when using deprecated parameters
+==== E_USER_DEPRECATED notice when using deprecated parameters
 
 Starting from elasticsearch-php 7.4.0, we generate a PHP 
 https://www.php.net/manual/en/errorfunc.constants.php[E_USER_DEPRECATED] notice 
@@ -25,21 +25,21 @@ set_error_handler(function ($errno, $errstr) {
 ----
 
 [discrete]
-=== Moving from types to typeless APIs in {es} 7.0
+==== Moving from types to typeless APIs in {es} 7.0
 
 {es} 7.0 deprecated APIs that accept types, introduced new typeless APIs, and 
 removed support for the _default_ mapping. Read 
 https://www.elastic.co/blog/moving-from-types-to-typeless-apis-in-elasticsearch-7-0[this]
 blog post for more information.
 
 [discrete]
-=== Type hint and return type
+==== Type hint and return type
 
 Added type hints and return type declarations in all the code base where 
 possible. See PR https://github.com/elastic/elasticsearch-php/pull/897[#897].
 
 [discrete]
-=== PHP 7.1+ Requirement
+==== PHP 7.1+ Requirement
 
 We require using PHP 7.1+ for elasticsearch-php. PHP 7.0 is not supported since
 1st Jan 2019. Refer 

docs/community.asciidoc

@@ -1,8 +1,8 @@
 [[community_dsls]]
-== Community DSLs
+=== Community DSLs
 
 [discrete]
-=== ElasticsearchDSL
+==== ElasticsearchDSL
 
 https://github.com/ongr-io/ElasticsearchDSL[Link: ElasticsearchDSL]
 [quote, ElasticsearchDSL]
@@ -13,7 +13,7 @@ it to an array.
 __________________________
 
 [discrete]
-=== elasticsearcher
+==== elasticsearcher
 
 https://github.com/madewithlove/elasticsearcher[Link: elasticsearcher]
 
@@ -26,7 +26,7 @@ client.
 __________________________
 
 [discrete]
-=== ElasticSearchQueryDSL
+==== ElasticSearchQueryDSL
 
 https://github.com/gskema/elasticsearch-query-dsl-php[Link: ElasticSearchQueryDSL]
 
@@ -38,13 +38,14 @@ explicit naming.
 __________________________
 
 
-== Community Integrations
+[[community-integrations]]
+=== Community Integrations
 
 [discrete]
-=== Symfony
+==== Symfony
 
 [discrete]
-==== ONGR Elasticsearch Bundle
+===== ONGR Elasticsearch Bundle
 
 https://github.com/ongr-io/ElasticsearchBundle[Link: ONGR {es} Bundle]
 
@@ -70,7 +71,7 @@ Technical goodies:
 __________________________
 
 [discrete]
-==== FOS Elastica Bundle
+===== FOS Elastica Bundle
 
 https://github.com/FriendsOfSymfony/FOSElasticaBundle[Link: FOS Elastica Bundle]
 
@@ -87,10 +88,10 @@ __________________________
 
 
 [discrete]
-=== Drupal
+==== Drupal
 
 [discrete]
-==== {es} Connector
+===== {es} Connector
 
 https://www.drupal.org/project/elasticsearch_connector[Link: {es} Connector]
 
@@ -101,10 +102,10 @@ Drupal.
 __________________________
 
 [discrete]
-=== Laravel
+==== Laravel
 
 [discrete]
-==== shift31/Laravel-Elasticsearch
+===== shift31/Laravel-Elasticsearch
 
 https://github.com/shift31/laravel-elasticsearch[Link: shift31/Laravel-Elasticsearch]
 
@@ -115,7 +116,7 @@ __________________________
 
 
 [discrete]
-==== cviebrock/Laravel-Elasticsearch
+===== cviebrock/Laravel-Elasticsearch
 
 https://github.com/cviebrock/laravel-elasticsearch[Link: cviebrock/Laravel-Elasticsearch]
 
@@ -126,7 +127,7 @@ __________________________
 
 
 [discrete]
-==== Plastic
+===== Plastic
 
 https://github.com/sleimanx2/plastic[Link: Plastic]
 
@@ -138,10 +139,10 @@ mapping, querying, and storing eloquent models.
 __________________________
 
 [discrete]
-=== Helper
+==== Helper
 
 [discrete]
-==== Index Helper
+===== Index Helper
 
 https://github.com/Nexucis/es-php-index-helper[Link: nexucis/es-php-index-helper]
 

docs/configuration.asciidoc

@@ -9,6 +9,8 @@ Custom configuration is accomplished before the client is instantiated, through
 the ClientBuilder helper object. You can find all the configuration options and 
 check sample code that helps you replace the various components.
 
+To learn more about JSON in PHP, read <<php_json_objects>>.
+
 * <<host-config>>
 * <<set-retries>>
 * <<enabling_logger>>
@@ -24,6 +26,8 @@ check sample code that helps you replace the various components.
 * <<future_mode>>
 
 
+include::php_json_objects.asciidoc[]
+
 include::host-config.asciidoc[]
 
 include::set-retries.asciidoc[]

docs/helpers.asciidoc

@@ -0,0 +1,84 @@
+[[client-helpers]]
+== Client helpers
+
+The client comes with helpers to give you a more comfortable experience with 
+some APIs.
+
+
+[discrete]
+[[iterators]]
+=== Iterators
+
+
+[discrete]
+[[search-response-iterator]]
+==== Search response iterator
+
+The `SearchResponseIterator` can be used to iterate page by page in a search 
+result using 
+https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html#paginate-search-results[pagination].
+
+An example as follows:
+
+[source,php]
+----
+use Elasticsearch\Helper\Iterators\SearchResponseIterator;
+
+$search_params = [
+    'scroll'      => '5m', // period to retain the search context
+    'index'       => '<name of index>', // here the index name
+    'size'        => 100, // 100 results per page
+    'body'        => [
+        'query' => [
+            'match_all' => new StdClass // {} in JSON
+        ]
+    ]
+];
+// $client is Elasticsearch\Client instance
+$pages = new SearchResponseIterator($client, $search_params);
+
+// Sample usage of iterating over page results
+foreach($pages as $page) {
+    // do something with hit e.g. copy its data to another index
+    // e.g. prints the number of document per page (100)
+    echo count($page['hits']['hits']), PHP_EOL;
+}
+----
+
+
+[discrete]
+[[search-hit-iterator]]
+==== Search hit iterator
+
+The `SearchHitIterator` can be used to iterate in a `SearchResponseIterator` 
+without worrying about 
+https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html#paginate-search-results[pagination].
+
+An example as follows:
+
+[source,php]
+----
+use Elasticsearch\Helper\Iterators\SearchHitIterator;
+use Elasticsearch\Helper\Iterators\SearchResponseIterator;
+
+$search_params = [
+    'scroll'      => '5m', // period to retain the search context
+    'index'       => '<name of index>', // here the index name
+    'size'        => 100, // 100 results per page
+    'body'        => [
+        'query' => [
+            'match_all' => new StdClass // {} in JSON
+        ]
+    ]
+];
+// $client is Elasticsearch\Client instance
+$pages = new SearchResponseIterator($client, $search_params);
+$hits = new SearchHitIterator($pages);
+
+// Sample usage of iterating over hits
+foreach($hits as $hit) {
+    // do something with hit e.g. write to CSV, update a database, etc
+    // e.g. prints the document id
+    echo $hit['_id'], PHP_EOL;
+}
+----

docs/index.asciidoc

@@ -15,10 +15,8 @@ include::operations.asciidoc[]
 
 include::build/classes.asciidoc[]
 
-include::php_json_objects.asciidoc[]
+include::helpers.asciidoc[]
 
-include::breaking-changes.asciidoc[]
-
-include::community.asciidoc[]
+include::release-notes.asciidoc[]
 
 include::redirects.asciidoc[]

docs/overview.asciidoc

@@ -14,11 +14,22 @@ added to the client (cluster state sniffing, round-robin requests, and so on)
 but largely it is very barebones. This was intentional; we want a common base 
 that more sophisticated libraries can build on top of.
 
+
 [discrete]
 [[psr-7-standard]]
 === PSR 7 standard
 
 The {es} PHP client uses the https://www.php-fig.org/psr/[PSR] 7 standard. This 
 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].
+https://www.php-fig.org/psr/psr-7/[PSR 7 standard documentation].
+
+
+* <<community_dsls>>
+* <<community-integrations>>
+* <<breaking_changes>>
+
+
+include::community.asciidoc[]
+
+include::breaking-changes.asciidoc[]

docs/php_json_objects.asciidoc

@@ -1,13 +1,13 @@
 [[php_json_objects]]
-== Dealing with JSON arrays and objects in PHP
+=== Dealing with JSON arrays and objects in PHP
 
 A common source of confusion with the client revolves around JSON arrays and 
 objects, and how to specify them in PHP. In particular, problems are caused by 
 empty objects and arrays of objects. This page shows you some common patterns
 used in {es} JSON API and how to convert that to a PHP representation.
 
 [discrete]
-=== Empty Objects
+==== Empty Objects
 
 The {es} API uses empty JSON objects in several locations which can cause 
 problems for PHP. Unlike other languages, PHP does not have a "short" notation 
@@ -63,7 +63,7 @@ solution is the only way to acomplish the goal in PHP... there is no "short"
 version of an empty object.
 
 [discrete]
-=== Arrays of Objects
+==== Arrays of Objects
 
 Another common pattern in {es} DSL is an array of objects. For example, consider 
 adding a sort to your query:
@@ -126,7 +126,7 @@ $results = $client->search($params);
 ----
 
 [discrete]
-=== Arrays of empty objects
+==== Arrays of empty objects
 
 Occasionally, you'll encounter DSL that requires both of the previous patterns. 
 The function score query is a good example, it sometimes requires an array of