Merge pull request #1007 from szabosteve/7.x.json.index

[DOCS] Fine-tunes JSON arrays and index operations pages in PHP client book

Author: szabosteve

docs/index-operations.asciidoc

@@ -1,13 +1,16 @@
 [[index_management]]
-== Index Management Operations
+== Index management operations
+
+Index management operations allow you to manage the indices in your {es} 
+cluster, such as creating, deleting and updating indices and their 
+mappings/settings.
 
-Index management operations allow you to manage the indices in your Elasticsearch cluster, such as creating, deleting and
-updating indices and their mappings/settings.
 
 === Create an index
 
-The index operations are all contained under a distinct namespace, separated from other methods that are on the root
-client object.  As an example, let's create a new index:
+The index operations are all contained under a distinct namespace, separated 
+from other methods that are on the root client object. As an example, let's 
+create a new index:
 
 [source,php]
 ----
@@ -21,8 +24,9 @@ $response = $client->indices()->create($params);
 ----
 {zwsp} +
 
-You can specify any parameters that would normally be included in a new index creation API.  All parameters that
-would normally go in the request body are located in the 'body' parameter:
+You can specify any parameters that would normally be included in a new index 
+creation API. All parameters that would normally go in the request body are 
+located in the 'body' parameter:
 
 [source,php]
 ----
@@ -56,11 +60,13 @@ $response = $client->indices()->create($params);
 ----
 {zwsp} +
 
+
 === Create an index (advanced example)
 
-This is a more complicated example of creating an index, showing how to define analyzers, tokenizers, filters and
-index settings. Although essentially the same as the previous example, the more complicated example can be helpful
-for "real world" usage of the client, since this particular syntax is easy to mess up.
+This is a more complicated example of creating an index, showing how to define 
+analyzers, tokenizers, filters and index settings. Although essentially the same 
+as the previous example, the more complicated example can be helpful for "real 
+world" usage of the client since this particular syntax is easy to mess up.
 
 [source,php]
 ----
@@ -125,9 +131,12 @@ $params = [
 ];
 $client->indices()->create($params);
 ----
-<1> The top level `settings` contains config about the index (# of shards, etc) as well as analyzers
-<2> `analysis` is nested inside of `settings`, and contains tokenizers, filters, char filters and analyzers
-<3> `mappings` is another element nested inside of `settings`, and contains the mappings for various types
+<1> The top level `settings` contains config about the index (# of shards, etc) 
+as well as analyzers.
+<2> `analysis` is nested inside of `settings`, and contains tokenizers, filters, 
+char filters and analyzers.
+<3> `mappings` is another element nested inside of `settings`, and contains the 
+mappings for various types.
 
 
 === Delete an index
@@ -141,8 +150,10 @@ $response = $client->indices()->delete($params);
 ----
 {zwsp} +
 
-=== Put Settings API
-The Put Settings API allows you to modify any index setting that is dynamic:
+
+=== PUT Settings API
+
+The PUT Settings API allows you to modify any index setting that is dynamic:
 
 [source,php]
 ----
@@ -160,9 +171,11 @@ $response = $client->indices()->putSettings($params);
 ----
 {zwsp} +
 
-=== Get Settings API
 
-Get Settings API will show you the currently configured settings for one or more indexes:
+=== GET Settings API
+
+The GET Settings API shows you the currently configured settings for one or more 
+indices:
 
 [source,php]
 ----
@@ -178,9 +191,10 @@ $response = $client->indices()->getSettings($params);
 ----
 {zwsp} +
 
-=== Put Mappings API
 
-The Put Mappings API allows you to modify or add to an existing index's mapping.
+=== PUT Mappings API
+
+The PUT Mappings API allows you to modify or add to an existing index's mapping.
 
 [source,php]
 ----
@@ -208,34 +222,45 @@ $client->indices()->putMapping($params);
 ----
 {zwsp} +
 
-=== Get Mappings API
 
-The Get Mappings API will return the mapping details about your indexes.  Depending on the mappings that you wish to retrieve, you can specify one of more indexes:
+=== GET Mappings API
+
+The GET Mappings API returns the mapping details about your indices. Depending 
+on the mappings that you wish to retrieve, you can specify one of more indices:
 
 [source,php]
 ----
-// Get mappings for all indexes
+// Get mappings for all indices
 $response = $client->indices()->getMapping();
 
 // Get mappings in 'my_index'
 $params = ['index' => 'my_index'];
 $response = $client->indices()->getMapping($params);
 
-// Get mappings for two indexes
+// Get mappings for two indices
 $params = [
     'index' => [ 'my_index', 'my_index2' ]
 ];
 $response = $client->indices()->getMapping($params);
 ----
 {zwsp} +
 
-=== Other APIs in the Indices Namespace
-There are a number of other APIs in the indices namespace that allow you to manage your elasticsearch indexes (add/remove templates, flush segments, close indexes, etc).
 
-If you use an IDE with autocompletion, you should be able to easily explore the indices namespace by typing:
+=== Other APIs in the indices namespace
+
+There are a number of other APIs in the indices namespace that allow you to 
+manage your {es} indices (add/remove templates, flush segments, close indices, 
+etc).
+
+If you use an IDE with autocompletion, you should be able to easily explore the 
+indices namespace by typing:
 
 [source,php]
 ----
 $client->indices()->
 ----
-And perusing the list of available methods.  Alternatively, browsing the `\Elasticsearch\Namespaces\Indices.php` file will show you the full list of available method calls (as well as parameter lists in the comments for each method).
+
+And perusing the list of available methods. Alternatively, browsing the 
+`\Elasticsearch\Namespaces\Indices.php` file shows you the full list of 
+available method calls (as well as parameter lists in the comments for each 
+method).

docs/php_json_objects.asciidoc

@@ -1,17 +1,19 @@
 [[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 will show you some common patterns
-used in Elasticsearch JSON API, and how to convert that to a PHP representation
+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.
 
 === Empty Objects
 
-The Elasticsearch API uses empty JSON objects in several locations, and this can cause problems for PHP.  Unlike other
-languages, PHP does not have a "short" notation for empty objects and so many developers are unaware how to specify
-an empty object.
+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 
+for empty objects and many developers are unaware how to specify an empty 
+object.
 
-Consider adding a Highlight to a query:
+Consider adding a highlight to a query:
 
 [source,json]
 ----
@@ -30,9 +32,10 @@ Consider adding a Highlight to a query:
 ----
 <1> This empty JSON object is what causes problems.
 
-The problem is that PHP will automatically convert `"content" : {}` into `"content" : []`, which is no longer valid
-Elasticsearch DSL.  We need to tell PHP that the empty object is explicitly an object, not an array.  To define this
-query in PHP, you would do:
+The problem is that PHP will automatically convert `"content" : {}` into 
+`"content" : []`, which is no longer valid {es} DSL. We need to tell PHP that 
+the empty object is explicitly an object, not an array. To define this query in 
+PHP, you would do:
 
 [source,json]
 ----
@@ -50,15 +53,18 @@ $params['body'] = array(
 );
 $results = $client->search($params);
 ----
-<1> We use the generic PHP stdClass object to represent an empty object.  The JSON will now encode correctly.
+<1> We use the generic PHP stdClass object to represent an empty object. The 
+JSON now encodes correctly.
 
-By using an explicit stdClass object, we can force the `json_encode` parser to correctly output an empty object, instead
-of an empty array.  Sadly, this verbose solution is the only way to acomplish the goal in PHP...there is no "short"
+By using an explicit stdClass object, we can force the `json_encode` parser to 
+correctly output an empty object, instead of an empty array. This verbose 
+solution is the only way to acomplish the goal in PHP... there is no "short"
 version of an empty object.
 
 === Arrays of Objects
 
-Another common pattern in Elasticsearch DSL is an array of objects.  For example, consider adding a sort to your query:
+Another common pattern in {es} DSL is an array of objects. For example, consider 
+adding a sort to your query:
 
 [source,json]
 ----
@@ -72,11 +78,12 @@ Another common pattern in Elasticsearch DSL is an array of objects.  For example
     ]
 }
 ----
-<1> "sort" contains an array of JSON objects
+<1> "sort" contains an array of JSON objects.
 
-This arrangement is *very* common, but the construction in PHP can be tricky since it requires nesting arrays.  The
-verbosity of PHP tends to obscure what is actually going on.  To construct an array of objects, you actually need
-an array of arrays:
+This arrangement is very common, but the construction in PHP can be tricky since 
+it requires nesting arrays. The verbosity of PHP tends to obscure what is 
+actually going on. To construct an array of objects, you actually need an array 
+of arrays:
 
 [source,json]
 ----
@@ -97,8 +104,8 @@ $results = $client->search($params);
 <2> This array encodes the `{"time" : {"order" : "desc"}}` object
 <3> This array encodes the `{"popularity" : {"order" : "desc"}}` object
 
-If you are on PHP 5.4+, I would strongly encourage you to use the short array syntax.  It makes these nested arrays
-much simpler to read:
+If you are on PHP 5.4+, we strongly encourage you to use the short array syntax. 
+It makes these nested arrays much simpler to read:
 
 [source,json]
 ----
@@ -118,10 +125,12 @@ $results = $client->search($params);
 
 === 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 objects, and some of those objects might be empty JSON 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 
+objects, and some of those objects might be empty JSON objects.
 
 Given this query:
+
 [source,json]
 ----
 {