1[[serializers]] 2=== Serializers 3 4The client has three serializers available. You will most likely never need 5to change the serializer, unless you have special requirements or are 6implementing a new protocol. 7 8The job of the serializer is to encode the outgoing request body and decode the 9incoming response body. In 99% of cases, this is a simple conversion to/from 10JSON. 11 12The default serializer is the `SmartSerializer`. 13 14 15[discrete] 16==== SmartSerializer 17 18[discrete] 19===== Serialize() 20 21The `SmartSerializer` inspects the data to be encoded. If the request body is 22provided as a string, it is passed directly to {es} as a string. This allows 23users to provide raw JSON, or raw strings for certain endpoints that don't have 24structure (such as the Analyze endpoint). 25 26If the data is an array, it is converted to JSON. If the data provided was an 27empty array, the serializer manually converts the JSON from an empty array 28(`[]`) to an empty object (`{}`) so that it is valid JSON for {es} request 29bodies. 30 31 32[discrete] 33===== Deserialize() 34 35When decoding the response body, the `SmartSerializer` introspects the 36`content_type` headers to determine the appropriate encoding. If the data is 37encoded as JSON, it is decoded into an array using `json_decode`. Otherwise, it 38is returned as a string. 39 40This functionality is required to cooperate with endpoints such as the `Cat` 41endpoints, which return tabular text instead of JSON. 42 43 44[discrete] 45===== Selecting the SmartSerializer 46 47The `SmartSerializer` is selected by default, but if you wish to manually 48configure it for explicitness, you can do so by using the `setSerializer()` 49method on the `ClientBuilder` object: 50 51[source,php] 52---- 53$client = ClientBuilder::create() 54 ->setSerializer('\Elasticsearch\Serializers\SmartSerializer'); 55 ->build(); 56---- 57 58Note that the serializer is configured by specifying a namespace path to the 59serializer. 60 61 62[discrete] 63==== ArrayToJSONSerializer 64 65 66[discrete] 67===== Serialize() 68 69The `ArrayToJSONSerializer` inspects the data to be encoded. If the request body 70is provided as a string, it is passed directly to {es} as a string. This allows 71users to provide raw JSON, or raw strings for certain endpoints that don't have 72structure (such as the Analyze endpoint). 73 74If the data is an array, it is converted to json. If the data provided was an 75empty array, the serializer manually converts the JSON from an empty array 76(`[]`) to an empty object (`{}`) so that it is valid JSON for {es} request 77bodies. 78 79 80[discrete] 81===== Deserialize() 82 83When decoding the response body, everything is decoded to JSON from JSON. If the 84data is not valid JSON, `null` will be returned. 85 86 87[discrete] 88===== Selecting the ArrayToJSONSerializer 89 90You can select `ArrayToJSONSerializer` by using the `setSerializer()` method on 91the `ClientBuilder` object: 92 93 94[source,php] 95---- 96$client = ClientBuilder::create() 97 ->setSerializer('\Elasticsearch\Serializers\ArrayToJSONSerializer'); 98 ->build(); 99---- 100 101Note that the serializer is configured by specifying a namespace path to the 102serializer. 103 104 105[discrete] 106==== EverythingToJSONSerializer 107 108 109[discrete] 110===== Serialize() 111 112The `EverythingToJSONSerializer` tries to convert everything to JSON. 113 114If the data provided was an empty array, the serializer manually converts the 115JSON from an empty array (`[]`) to an empty object (`{}`) so that it is valid 116JSON for Elasticsearch request bodies. 117 118If the data was not an array and/or not convertible to JSON, the method returns 119`null`. 120 121 122[discrete] 123===== Deserialize() 124 125When decoding the response body, everything is decoded to JSON from JSON. If the 126data is not valid JSON, `null` is returned. 127 128 129[discrete] 130==== Selecting the EverythingToJSONSerializer 131 132You can select `EverythingToJSONSerializer` by using the `setSerializer()` 133method on the ClientBuilder object: 134 135[source,php] 136---- 137$client = ClientBuilder::create() 138 ->setSerializer('\Elasticsearch\Serializers\EverythingToJSONSerializer'); 139 ->build(); 140---- 141 142Note that the serializer is configured by specifying a namespace path to the 143serializer. 144 145 146[discrete] 147==== Implementing your own Serializer 148 149If you want to use your own custom serializer, you need to implement the 150`SerializerInterface` interface. Please keep in mind that the client uses a 151single Serializer object for all endpoints and all connections. 152 153 154[source,php] 155---- 156class MyCustomSerializer implements SerializerInterface 157{ 158 159 /** 160 * Serialize request body 161 * 162 * @param string|array $data Request body 163 * 164 * @return string 165 */ 166 public function serialize($data) 167 { 168 // code here 169 } 170 171 /** 172 * Deserialize response body 173 * 174 * @param string $data Response body 175 * @param array $headers Response Headers 176 * 177 * @return array|string 178 */ 179 public function deserialize($data, $headers) 180 { 181 // code here 182 } 183} 184---- 185{zwsp} + 186 187To then use your custom serializer, you can specify the namespace path in the 188`setSerializer()` method of the `ClientBuilder` object: 189 190[source,php] 191---- 192$client = ClientBuilder::create() 193 ->setSerializer('\MyProject\Serializers\MyCustomSerializer'); 194 ->build(); 195---- 196 197Alternatively, if your serializer has a constructor or further initialization 198that should occur before given to the client, you can instantiate an object and 199provide that instead: 200 201[source,php] 202---- 203$mySerializer = new MyCustomSerializer($a, $b, $c); 204$mySerializer->setFoo("bar"); 205 206$client = ClientBuilder::create() 207 ->setSerializer($mySerializer); 208 ->build(); 209---- 210 211 212[discrete] 213==== Quick setup 214 215The majority of people will never need to change the default Serializer 216(`SmartSerializer`), but if you need to, it can be done via the 217`setSerializer()` method: 218 219[source,php] 220---- 221$serializer = '\Elasticsearch\Serializers\SmartSerializer'; 222$client = ClientBuilder::create() 223 ->setSerializer($serializer) 224 ->build(); 225----