Merge remote-tracking branch 'elasticsearch-php/7.x' into 7.x

Author: ezimuel

docs/crud.asciidoc

@@ -1,15 +1,21 @@
 [[indexing_documents]]
-== Indexing Documents
+== Indexing documents
 
-IMPORTANT: Please note that mapping types will disappear from Elasticsearch, read more https://www.elastic.co/guide/en/elasticsearch/reference/7.x/removal-of-types.html[here]. If you migrated types from Elasticsearch 6 to 7, you can address these with the `type` param.
+IMPORTANT: Please note that mapping types will disappear from {es}, read more 
+{ref-7x}/removal-of-types.html[here]. If you migrated types from {es} 6 to 7, 
+you can address these with the `type` param.
+
+When you add documents to {es}, you index JSON documents. This maps naturally to 
+PHP associative arrays, since they can easily be encoded in JSON. Therefore, in 
+Elasticsearch-PHP you create and pass associative arrays to the client for 
+indexing. There are several methods of ingesting data into {es} which we cover 
+here.
 
-When you add documents to Elasticsearch, you index JSON documents.  This maps naturally to PHP associative arrays, since
-they can easily be encoded in JSON.  Therefore, in Elasticsearch-PHP you create and pass associative arrays to the client
-for indexing.  There are several methods of ingesting data into Elasticsearch, which we will cover here.
 
 === Single document indexing
 
-When indexing a document, you can either provide an ID or let elasticsearch generate one for you.
+When indexing a document, you can either provide an ID or let {es} generate one 
+for you.
 
 {zwsp} +
 
@@ -40,7 +46,9 @@ $response = $client->index($params);
 ----
 {zwsp} +
 
-If you need to set other parameters, such as a `routing` value, you specify those in the array alongside the `index`, etc.  For example, let's set the routing and timestamp of this new document:
+If you need to set other parameters, such as a `routing` value, you specify 
+those in the array alongside the `index`, and others. For example, let's set the 
+routing and timestamp of this new document:
 
 .Additional parameters
 [source,php]
@@ -58,11 +66,14 @@ $response = $client->index($params);
 ----
 {zwsp} +
 
+
 === Bulk Indexing
 
-Elasticsearch also supports bulk indexing of documents.  The bulk API expects JSON action/metadata pairs, separated by
-newlines.  When constructing your documents in PHP, the process is similar.  You first create an action array object
-(e.g. `index` object), then you create a document body object.  This process repeats for all your documents.
+{es} also supports bulk indexing of documents. The bulk API expects JSON 
+action/metadata pairs, separated by newlines. When constructing your documents 
+in PHP, the process is similar. You first create an action array object (for 
+example, an `index` object), then you create a document body object. This 
+process repeats for all your documents.
 
 A simple example might look like this:
 
@@ -85,9 +96,9 @@ for($i = 0; $i < 100; $i++) {
 $responses = $client->bulk($params);
 ----
 
-In practice, you'll likely have more documents than you want to send in a single bulk request.  In that case, you need
-to batch up the requests and periodically send them:
-
+In practice, you'll likely have more documents than you want to send in a single 
+bulk request. In that case, you need to batch up the requests and periodically 
+send them:
 
 .Bulk indexing with batches
 [source,php]
@@ -126,11 +137,12 @@ if (!empty($params['body'])) {
 ----
 
 [[getting_documents]]
-== Getting Documents
+== Getting documents
 
-Elasticsearch provides realtime GETs of documents.  This means that as soon as the document has been indexed and your
-client receives an acknowledgement, you can immediately retrieve the document from any shard.  Get operations are
-performed by requesting a document by it's full `index/type/id` path:
+{es} provides realtime GETs of documents. This means that as soon as the 
+document is indexed and your client receives an acknowledgement, you can 
+immediately retrieve the document from any shard. Get operations are performed 
+by requesting a document by its full `index/type/id` path:
 
 [source,php]
 ----
@@ -145,15 +157,17 @@ $response = $client->get($params);
 {zwsp} +
 
 [[updating_documents]]
-== Updating Documents
+== Updating documents
 
-Updating a document allows you to either completely replace the contents of the existing document, or perform a partial
-update to just some fields (either changing an existing field, or adding new fields).
+Updating a document allows you to either completely replace the contents of the 
+existing document, or perform a partial update to just some fields (either 
+changing an existing field or adding new fields).
 
 === Partial document update
 
-If you want to partially update a document (e.g. change an existing field, or add a new one) you can do so by specifying
-the `doc` in the `body` parameter.  This will merge the fields in `doc` with the existing document
+If you want to partially update a document (for example, change an existing 
+field or add a new one) you can do so by specifying the `doc` in the `body` 
+parameter. This merges the fields in `doc` with the existing document.
 
 
 [source,php]
@@ -173,10 +187,12 @@ $response = $client->update($params);
 ----
 {zwsp} +
 
+
 === Scripted document update
 
-Sometimes you need to perform a scripted update, such as incrementing a counter or appending a new value to an array.
-To perform a scripted update, you need to provide a script and (usually) a set of parameters:
+Sometimes you need to perform a scripted update, such as incrementing a counter 
+or appending a new value to an array. To perform a scripted update, you need to 
+provide a script and usually a set of parameters:
 
 [source,php]
 ----
@@ -195,10 +211,12 @@ $response = $client->update($params);
 ----
 {zwsp} +
 
+
 === Upserts
 
-Upserts are "Update or Insert" operations.  This means an upsert will attempt to run your update script, but if the document
-does not exist (or the field you are trying to update doesn't exist), default values will be inserted instead.
+Upserts are "Update or Insert" operations. This means an upsert attempts to run 
+your update script, but if the document does not exist (or the field you are 
+trying to update doesn't exist), default values are inserted instead.
 
 [source,php]
 ----
@@ -222,10 +240,12 @@ $response = $client->update($params);
 ----
 {zwsp} +
 
+
 [[deleting_documents]]
 == Deleting documents
 
-Finally, you can delete documents by specifying their full `/index/_doc_/id` path:
+Finally, you can delete documents by specifying their full `/index/_doc_/id` 
+path:
 
 [source,php]
 ----

docs/namespaces.asciidoc

@@ -2,22 +2,22 @@
 == Namespaces
 
 The client has a number of "namespaces", which generally expose administrative
-functionality.  The namespaces correspond to the various administrative endpoints
-in Elasticsearch.  This is a complete list of namespaces:
+functionality. The namespaces correspond to the various administrative endpoints
+in {es}. This is a complete list of namespaces:
 
 
 [width="40%",options="header",frame="topbot"]
 |============================
-| Namespace  | Functionality
+| Namespace    | Functionality
 | `indices()`  | Index-centric stats and info
 | `nodes()`    | Node-centric stats and info
 | `cluster()`  | Cluster-centric stats and info
 | `snapshot()` | Methods to snapshot/restore your cluster and indices
 | `cat()`      | Access to the Cat API (which is generally used standalone from the command line
 |============================
 
-Some methods are available in several different namespaces, which give you
-the same information but grouped into different contexts.  To see how these
+Some methods are available in several different namespaces, which give you the 
+same information but grouped into different contexts. To see how these 
 namespaces work, let's look at the `_stats` output:
 
 
@@ -39,8 +39,8 @@ $response = $client->cluster()->stats();
 ----
 {zwsp} +
 
-As you can see, the same `stats()` call is made through three different
-namespaces.  Sometimes the methods require parameters.  These parameters work
+As you can see, the same `stats()` call is made through three different 
+namespaces. Sometimes the methods require parameters. These parameters work
 just like any other method in the library.
 
 For example, we can requests index stats about a specific index, or multiple
@@ -60,7 +60,7 @@ $response = $client->indices()->stats($params);
 ----
 {zwsp} +
 
-As another example, here is how you might add an alias to an existing index:
+The following example shows how you can add an alias to an existing index:
 
 [source,php]
 ----
@@ -77,6 +77,7 @@ $params['body'] = array(
 $client->indices()->updateAliases($params);
 ----
 
-Notice how both the `stats` calls and the updateAlias took a variety of parameters,
-each according to what the particular API requires.  The `stats` API only requires
-an index name(s), while the `updateAlias` requires a body of actions.
+Notice how both the `stats` calls and the updateAlias took a variety of 
+parameters, each according to what the particular API requires. The `stats` API 
+only requires an index name(s), while the `updateAlias` requires a body of 
+actions.

docs/search-operations.asciidoc

@@ -1,14 +1,17 @@
 [[search_operations]]
-== Search Operations
+== Search operations
 
-Well...it isn't called elasticsearch for nothing!  Let's talk about search operations in the client.
+Well...it isn't called {es} for nothing! Let's talk about search operations in 
+the client.
 
-The client gives you full access to every query and parameter exposed by the REST API, following the naming scheme as
-much as possible. Let's look at a few examples so you can become familiar with the syntax.
+The client gives you full access to every query and parameter exposed by the 
+REST API, following the naming scheme as much as possible. Let's look at a few 
+examples so you can become familiar with the syntax.
 
-=== Match Query
 
-Here is a standard curl for a Match query:
+=== Match query
+
+Here is a standard curl for a match query:
 
 [source,shell]
 ----
@@ -22,6 +25,7 @@ curl -XGET 'localhost:9200/my_index/_search' -d '{
 ----
 {zwsp} +
 
+
 And here is the same query constructed in the client:
 
 [source,php]
@@ -41,9 +45,11 @@ $results = $client->search($params);
 ----
 {zwsp} +
 
-Notice how the structure and layout of the PHP array is identical to that of the JSON request body.  This makes it very
-simple to convert JSON examples into PHP.  A quick method to check your PHP array (for more complex examples) is to
-encode it back to JSON and check by eye:
+
+Notice how the structure and layout of the PHP array is identical to that of the 
+JSON request body. This makes it very simple to convert JSON examples into PHP. 
+A quick method to check your PHP array (for more complex examples) is to encode 
+it back to JSON and check it:
 
 [source,php]
 ----
@@ -68,8 +74,9 @@ print_r(json_encode($params['body']));
 
 .Using Raw JSON
 ****
-Sometimes it is convenient to use raw JSON for testing purposes, or when migrating from a different system.  You can
-use raw JSON as a string in the body, and the client will detect this automatically:
+Sometimes it is convenient to use raw JSON for testing purposes, or when 
+migrating from a different system. You can use raw JSON as a string in the body, 
+and the client detects this automatically:
 
 [source,php]
 ----
@@ -91,8 +98,10 @@ $results = $client->search($params);
 ****
 {zwsp} +
 
-Search results follow the same format as Elasticsearch search response, the only difference is that the JSON response is
-serialized back into PHP arrays. Working with the search results is as simple as iterating over the array values:
+
+Search results follow the same format as {es} search response, the only 
+difference is that the JSON response is serialized back into PHP arrays. Working 
+with the search results is as simple as iterating over the array values:
 
 [source,php]
 ----
@@ -117,9 +126,12 @@ $doc   = $results['hits']['hits'][0]['_source'];
 ----
 {zwsp} +
 
+
 === Bool Queries
 
-Bool queries can be easily constructed using the client. For example, this query:
+Bool queries can be easily constructed using the client. For example, this 
+query:
+
 [source,shell]
 ----
 curl -XGET 'localhost:9200/my_index/_search' -d '{
@@ -139,7 +151,9 @@ curl -XGET 'localhost:9200/my_index/_search' -d '{
 ----
 {zwsp} +
 
-Would be structured like this (Note the position of the square brackets):
+
+Would be structured like this (note the position of the square brackets):
+
 [source,php]
 ----
 $params = [
@@ -160,14 +174,18 @@ $results = $client->search($params);
 ----
 {zwsp} +
 
-Notice that the `must` clause accepts an array of arrays.  This will be serialized into an array of JSON objects internally,
-so the final resulting output will be identical to the curl example.  For more details about arrays vs objects in PHP,
+
+Notice that the `must` clause accepts an array of arrays. This is serialized 
+into an array of JSON objects internally, so the final resulting output is 
+identical to the curl example. For more details about arrays and objects in PHP,
 see <<php_json_objects, Dealing with JSON Arrays and Objects in PHP>>.
 
+
 === A more complicated example
 
-Let's construct a slightly more complicated example: a boolean query that contains both a filter and a query.
-This is a very common activity in elasticsearch queries, so it will be a good demonstration.
+Let's construct a slightly more complicated example: a boolean query that 
+contains both a filter and a query. This is a very common activity in {es} 
+queries, so it will be a good demonstration.
 
 The curl version of the query:
 
@@ -188,6 +206,7 @@ curl -XGET 'localhost:9200/my_index/_search' -d '{
 ----
 {zwsp} +
 
+
 And in PHP:
 
 [source,php]
@@ -216,16 +235,19 @@ $results = $client->search($params);
 
 === Scrolling
 
-The Scrolling functionality of Elasticsearch is used to paginate over many documents in a bulk manner, such as exporting
-all the documents belonging to a single user.  It is more efficient than regular search because it doesn't need to maintain
-an expensive priority queue ordering the documents.
+The scrolling functionality of {es} is used to paginate over many documents in a 
+bulk manner, such as exporting all the documents belonging to a single user. It 
+is more efficient than regular search because it doesn't need to maintain an 
+expensive priority queue ordering the documents.
 
-Scrolling works by maintaining a "point in time" snapshot of the index which is then used to page over.
-This window allows consistent paging even if there is background indexing/updating/deleting.  First, you execute a search
-request with `scroll` enabled.  This returns a "page" of documents, and a scroll_id which is used to continue
-paginating through the hits.
+Scrolling works by maintaining a "point in time" snapshot of the index which is 
+then used to page over. This window allows consistent paging even if there is 
+background indexing/updating/deleting. First, you execute a search request with 
+`scroll` enabled. This returns a "page" of documents, and a `scroll_id` which is 
+used to continue paginating through the hits.
 
-More details about scrolling can be found in the https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html#request-body-search-scroll[Link: reference documentation].
+More details about scrolling can be found in the 
+{ref-7x}/search-request-body.html#request-body-search-scroll[reference documentation].
 
 This is an example which can be used as a template for more advanced operations: