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----