Merge pull request #1023 from szabosteve/7.x.serial.version

[DOCS] Fine-tunes serializers and required PHP version pages in the PHP book

Author: szabosteve

docs/php-version-requirement.asciidoc

@@ -2,4 +2,6 @@
 == PHP Version Requirement
 
 Version 7.0 of Elasticsearch-PHP requires PHP version 7.1.0 or higher.
-In addition, it requires the native JSON extension to be version 1.3.7 or higher.
+
+In addition, it requires the native JSON extension to be version 1.3.7 or 
+higher.

docs/serializers.asciidoc

@@ -1,41 +1,47 @@
 [[serializers]]
 == Serializers
 
-The client has three serializers available.  You will most likely never need
-to change the serializer, unless you have special requirements or are
+The client has three serializers available. You will most likely never need
+to change the serializer, unless you have special requirements or are 
 implementing a new protocol.
 
-The job of the serializer is to encode the outgoing request body and decode
-the incoming response body.  In 99% of cases, this is a simple conversion
-to/from JSON.
+The job of the serializer is to encode the outgoing request body and decode the 
+incoming response body. In 99% of cases, this is a simple conversion to/from 
+JSON.
+
+The default serializer is the `SmartSerializer`.
 
-The default serializer is the `SmartSerializer`
 
 === SmartSerializer
+
 ==== Serialize()
-The `SmartSerializer` inspects the data to be encoded.  If the request body
-is provided as a string, it is passed directly to Elasticsearch as a string.
-This allows users to provide raw JSON, or raw strings for certain endpoints that
-dont have structure (such as the Analyze endpoint).
-
-If the data is an array, it is converted to json.  If the data provided was an
-empty array, the serializer manually converts the JSON from an empty array (`[]`)
-to an empty object (`{}`) so that it is valid JSON for Elasticsearch request
+
+The `SmartSerializer` inspects the data to be encoded. If the request body is 
+provided as a string, it is passed directly to {es} as a string. This allows 
+users to provide raw JSON, or raw strings for certain endpoints that don't have 
+structure (such as the Analyze endpoint).
+
+If the data is an array, it is converted to JSON. If the data provided was an
+empty array, the serializer manually converts the JSON from an empty array 
+(`[]`) to an empty object (`{}`) so that it is valid JSON for {es} request 
 bodies.
 
 ==== Deserialize()
-When decoding the response body, the `SmartSerializer` introspects the
-`content_type` headers to determine the appropriate encoding.  If the data is
-encoded as JSON, it is decoded into an array using `json_decode`.  Otherwise,
-it is returned as a string.
 
-This functionality is required to cooperate with endpoints such as the `Cat`
+When decoding the response body, the `SmartSerializer` introspects the 
+`content_type` headers to determine the appropriate encoding. If the data is
+encoded as JSON, it is decoded into an array using `json_decode`. Otherwise, it 
+is returned as a string.
+
+This functionality is required to cooperate with endpoints such as the `Cat` 
 endpoints, which return tabular text instead of JSON.
 
+
 ==== Selecting the SmartSerializer
 
-The SmartSerializer is selected by default, but if you wish to manually configure it for explicitness, you can
-do so by using the `setSerializer()` method on the ClientBuilder object:
+The `SmartSerializer` is selected by default, but if you wish to manually 
+configure it for explicitness, you can do so by using the `setSerializer()` 
+method on the `ClientBuilder` object:
 
 [source,php]
 ----
@@ -44,27 +50,36 @@ $client = ClientBuilder::create()
             ->build();
 ----
 
-Note that the serializer is configured by specifying a namespace path to the serializer.
+Note that the serializer is configured by specifying a namespace path to the 
+serializer.
+
 
 === ArrayToJSONSerializer
+
 ==== Serialize()
-The `ArrayToJSONSerializer` inspects the data to be encoded.  If the request body
-is provided as a string, it is passed directly to Elasticsearch as a string.
-This allows users to provide raw JSON, or raw strings for certain endpoints that
-dont have structure (such as the Analyze endpoint).
-
-If the data is an array, it is converted to json.  If the data provided was an
-empty array, the serializer manually converts the JSON from an empty array (`[]`)
-to an empty object (`{}`) so that it is valid JSON for Elasticsearch request
+
+The `ArrayToJSONSerializer` inspects the data to be encoded. If the request body
+is provided as a string, it is passed directly to {es} as a string. This allows 
+users to provide raw JSON, or raw strings for certain endpoints that don't have 
+structure (such as the Analyze endpoint).
+
+If the data is an array, it is converted to json. If the data provided was an
+empty array, the serializer manually converts the JSON from an empty array 
+(`[]`) to an empty object (`{}`) so that it is valid JSON for {es} request 
 bodies.
 
+
 ==== Deserialize()
-When decoding the response body, everything is decoded to JSON from JSON.  If
-the data is not valid JSON, `null` will be returned.
+
+When decoding the response body, everything is decoded to JSON from JSON. If the 
+data is not valid JSON, `null` will be returned.
+
 
 ==== Selecting the ArrayToJSONSerializer
 
-You can select  `ArrayToJSONSerializer` by using the `setSerializer()` method on the ClientBuilder object:
+You can select `ArrayToJSONSerializer` by using the `setSerializer()` method on 
+the `ClientBuilder` object:
+
 
 [source,php]
 ----
@@ -73,26 +88,32 @@ $client = ClientBuilder::create()
             ->build();
 ----
 
-Note that the serializer is configured by specifying a namespace path to the serializer.
+Note that the serializer is configured by specifying a namespace path to the 
+serializer.
+
 
 === EverythingToJSONSerializer
+
 ==== Serialize()
+
 The `EverythingToJSONSerializer` tries to convert everything to JSON.
 
-If the data provided was an empty array, the serializer manually converts the
+If the data provided was an empty array, the serializer manually converts the 
 JSON from an empty array (`[]`) to an empty object (`{}`) so that it is valid
 JSON for Elasticsearch request bodies.
 
 If the data was not an array and/or not convertible to JSON, the method returns
 `null`.
 
 ==== Deserialize()
-When decoding the response body, everything is decoded to JSON from JSON.  If
-the data is not valid JSON, `null` will be returned.
+
+When decoding the response body, everything is decoded to JSON from JSON. If the 
+data is not valid JSON, `null` is returned.
 
 ==== Selecting the EverythingToJSONSerializer
 
-You can select  `EverythingToJSONSerializer` by using the `setSerializer()` method on the ClientBuilder object:
+You can select  `EverythingToJSONSerializer` by using the `setSerializer()` 
+method on the ClientBuilder object:
 
 [source,php]
 ----
@@ -101,11 +122,14 @@ $client = ClientBuilder::create()
             ->build();
 ----
 
-Note that the serializer is configured by specifying a namespace path to the serializer.
+Note that the serializer is configured by specifying a namespace path to the 
+serializer.
 
 === Implementing your own Serializer
-If you want to use your own custom serializer, you need to implement the `SerializerInterface` interface.  Please
-keep in mind that the client uses a single Serializer object for all endpoints and all connections.
+
+If you want to use your own custom serializer, you need to implement the 
+`SerializerInterface` interface. Please keep in mind that the client uses a 
+single Serializer object for all endpoints and all connections.
 
 
 [source,php]
@@ -141,8 +165,8 @@ class MyCustomSerializer implements SerializerInterface
 ----
 {zwsp} +
 
-To then use your custom serializer, you can specify the namespace path in the `setSerializer()` method of the ClientBuilder
-object:
+To then use your custom serializer, you can specify the namespace path in the 
+`setSerializer()` method of the `ClientBuilder` object:
 
 [source,php]
 ----
@@ -151,8 +175,9 @@ $client = ClientBuilder::create()
             ->build();
 ----
 
-Alternatively, if your serializer has a constructor or further initialization that should occur before given to the
-client, you can instantiate an object and provide that instead:
+Alternatively, if your serializer has a constructor or further initialization 
+that should occur before given to the client, you can instantiate an object and 
+provide that instead:
 
 [source,php]
 ----
@@ -162,6 +187,4 @@ $mySerializer->setFoo("bar");
 $client = ClientBuilder::create()
             ->setSerializer($mySerializer);
             ->build();
-----
-
-
+----