Enable the Client to keep requests

docs/configuration.asciidoc

@@ -376,6 +376,38 @@ Obviously, by doing this you take responsibility that all existing endpoints sti
 assume the responsibility of correctly wiring the Transport and Serializer into each endpoint.
 
 
+=== Keep Requests
+
+Notice: This is mainly used for debugging purposes.
+
+By default the client will only keep the latest request made to ElasticSearch saved in the latest connection. By enabling
+the Keep Requests part of the Client, the client will keep a record of all requests made during its lifecycle.
+This can be useful if you are interested in logging the requests and responses different from the default way this
+library logs the requests.
+
+If you wish to enable to client to keep requests you can use the setKeepRequests(true):
+
+[source,php]
+----------------------------
+
+$client = ClientBuilder::create()
+                    ->setKeepRequests(true)
+                    ->build();
+----------------------------
+
+Once the client has been built using the setKeepRequests(true), you can retrieve the requests using:
+
+[source,php]
+----------------------------
+
+$requests = $client->transport->getKeptRequests();
+
+//or
+
+$requests = $client->transport->keptRequests;
+----------------------------
+
+
 === Building the client from a configuration hash
 
 To help ease automated building of the client, all configurations can be provided in a setting

src/Elasticsearch/ClientBuilder.php

@@ -82,6 +82,9 @@ class ClientBuilder
     /** @var bool */
     private $sniffOnStart = false;
 
+    /** @var bool */
+    private $keepRequests = false;
+
     /** @var null|array  */
     private $sslCert = null;
 
@@ -387,6 +390,17 @@ public function setSniffOnStart($sniffOnStart)
         return $this;
     }
 
+    /**
+     * @param boolean $keepRequests
+     * @return $this
+     */
+    public function setKeepRequests($keepRequests)
+    {
+        $this->keepRequests = $keepRequests;
+
+        return $this;
+    }
+
     /**
      * @param string $cert The name of a file containing a PEM formatted certificate.
      * @param null|string $password
@@ -570,7 +584,7 @@ private function buildTransport()
         }
 
         if (is_null($this->transport)) {
-            $this->transport = new Transport($this->retries, $this->sniffOnStart, $this->connectionPool, $this->logger);
+            $this->transport = new Transport($this->retries, $this->sniffOnStart, $this->keepRequests, $this->connectionPool, $this->logger);
         }
     }
 

src/Elasticsearch/Connections/Connection.php

@@ -198,11 +198,23 @@ private function wrapHandler(callable $handler)
             $this->lastRequest = [];
             $this->lastRequest['request'] = $request;
 
+
+            $indexKey = count($transport->getKeptRequests());
+
+            if ($transport->keepRequests === true) {
+                $transport->keptRequests[$indexKey]['request'] = $request;
+            }
+
+
             // Send the request using the wrapped handler.
-            $response =  Core::proxy($handler($request), function ($response) use ($connection, $transport, $request, $options) {
+            $response =  Core::proxy($handler($request), function ($response) use ($connection, $transport, $request, $options, $indexKey) {
 
                 $this->lastRequest['response'] = $response;
 
+                if ($transport->keepRequests === true) {
+                    $transport->keptRequests[$indexKey]['response'] = $response;
+                }
+
                 if (isset($response['error']) === true) {
                     if ($response['error'] instanceof ConnectException || $response['error'] instanceof RingException) {
                         $this->log->warning("Curl exception encountered.");
@@ -272,6 +284,10 @@ private function wrapHandler(callable $handler)
                     if (isset($response['body']) === true) {
                         $response['body'] = stream_get_contents($response['body']);
                         $this->lastRequest['response']['body'] = $response['body'];
+
+                        if ($transport->keepRequests === true) {
+                            $transport->keptRequests[$indexKey]['response']['body'] = $response['body'];
+                        }
                     }
 
                     if ($response['status'] >= 400 && $response['status'] < 500) {

src/Elasticsearch/Transport.php

@@ -38,6 +38,12 @@ class Transport
     /** @var  Connection */
     public $lastConnection;
 
+    /** @var bool */
+    public $keepRequests = false;
+
+    /** @var array */
+    public $keptRequests = [];
+
     /** @var int  */
     public $retries;
 
@@ -47,18 +53,20 @@ class Transport
      *
      * @param int $retries
      * @param bool $sniffOnStart
+     * @param bool $keepRequests
      * @param ConnectionPool\AbstractConnectionPool $connectionPool
      * @param \Psr\Log\LoggerInterface $log    Monolog logger object
      */
 	// @codingStandardsIgnoreStart
 	// "Arguments with default values must be at the end of the argument list" - cannot change the interface
-    public function __construct($retries, $sniffOnStart = false, AbstractConnectionPool $connectionPool, LoggerInterface $log)
+    public function __construct($retries, $sniffOnStart = false, $keepRequests = false, AbstractConnectionPool $connectionPool, LoggerInterface $log)
     {
 	    // @codingStandardsIgnoreEnd
 
         $this->log            = $log;
         $this->connectionPool = $connectionPool;
         $this->retries        = $retries;
+        $this->keepRequests   = $keepRequests;
 
         if ($sniffOnStart === true) {
             $this->log->notice('Sniff on Start.');
@@ -178,4 +186,15 @@ public function getLastConnection()
     {
         return $this->lastConnection;
     }
+
+    /**
+     * Returns the array of requests performed from the client.  Mainly
+     * for debugging/testing purposes.
+     *
+     * @return array
+     */
+    public function getKeptRequests()
+    {
+        return $this->keptRequests;
+    }
 }