diff --git a/docs/breaking-changes.asciidoc b/docs/breaking-changes.asciidoc index ff9a190bd..844a85906 100644 --- a/docs/breaking-changes.asciidoc +++ b/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,7 +25,7 @@ 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 @@ -33,13 +33,13 @@ https://www.elastic.co/blog/moving-from-types-to-typeless-apis-in-elasticsearch- 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 diff --git a/docs/community.asciidoc b/docs/community.asciidoc index 21b9e1eb6..39511e02e 100644 --- a/docs/community.asciidoc +++ b/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] diff --git a/docs/configuration.asciidoc b/docs/configuration.asciidoc index b0063a661..567228204 100644 --- a/docs/configuration.asciidoc +++ b/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 <>. + * <> * <> * <> @@ -24,6 +26,8 @@ check sample code that helps you replace the various components. * <> +include::php_json_objects.asciidoc[] + include::host-config.asciidoc[] include::set-retries.asciidoc[] diff --git a/docs/helpers.asciidoc b/docs/helpers.asciidoc new file mode 100644 index 000000000..89631bc92 --- /dev/null +++ b/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' => '', // 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' => '', // 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; +} +---- \ No newline at end of file diff --git a/docs/index.asciidoc b/docs/index.asciidoc index f26b8925b..319852d51 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -15,10 +15,6 @@ include::operations.asciidoc[] include::build/classes.asciidoc[] -include::php_json_objects.asciidoc[] - -include::breaking-changes.asciidoc[] - -include::community.asciidoc[] +include::helpers.asciidoc[] include::redirects.asciidoc[] diff --git a/docs/overview.asciidoc b/docs/overview.asciidoc index 637be8436..d079f9d12 100644 --- a/docs/overview.asciidoc +++ b/docs/overview.asciidoc @@ -12,4 +12,13 @@ from one language to the next with minimal effort. The client is designed to be "unopinionated". There are a few universal niceties 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. \ No newline at end of file +that more sophisticated libraries can build on top of. + +* <> +* <> +* <> + + +include::community.asciidoc[] + +include::breaking-changes.asciidoc[] \ No newline at end of file diff --git a/docs/php_json_objects.asciidoc b/docs/php_json_objects.asciidoc index 1e1c39d53..fa29496dd 100644 --- a/docs/php_json_objects.asciidoc +++ b/docs/php_json_objects.asciidoc @@ -1,5 +1,5 @@ [[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 @@ -7,7 +7,7 @@ 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