Merge branch 'elastic-cloud'

Author: ezimuel

docs/configuration.asciidoc

@@ -88,6 +88,30 @@ $client = ClientBuilder::create()           // Instantiate a new ClientBuilder
 Only the `host` parameter is required for each configured host.  If not provided, the default port is `9200`.  The default
 scheme is `http`.
 
+=== Connect to Elastic Cloud
+
+If you want to connect to Elastic Cloud, you can use your Cloud ID and use basic authentication or ApiKey authentication to connect to it.
+
+[source,php]
+----
+$client = ClientBuilder::create()
+            ->setElasticCloudId('<elastic-cloud-id>')  <1>
+            ->setBasicAuthentication('<username>', '<secure-password>') <2>
+            ->build();
+----
+<1> Your Cloud ID provided by the Elastic Cloud platform
+<2> Your basic authentication credentials
+
+[source,php]
+----
+$client = ClientBuilder::create()
+            ->setElasticCloudId('<elastic-cloud-id>') <1>
+            ->setApiKey('<id>', '<api_key>') <2>
+            ->build();
+----
+<1> Your Cloud ID provided by the Elastic Cloud platform
+<2> Your ApiKey pair as described https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/security.html[here]
+
 === Authorization and Encryption
 
 For details about HTTP Authorization and SSL encryption, see
@@ -244,7 +268,7 @@ $client = ClientBuilder::create()
             ->build();
 ----
 
-For more details, please see the dedicated page on 
+For more details, please see the dedicated page on
 <<connection_pool,configuring connection pools>>.
 
 === Setting the Connection Selector

docs/security.asciidoc

@@ -24,6 +24,18 @@ $client = ClientBuilder::create()
 Credentials are provided per-host, which allows each host to have their own set of credentials.  All requests sent to the
 cluster will use the appropriate credentials depending on the node being talked to.
 
+=== ApiKey Authentication
+
+If your Elasticsearch cluster is secured by API keys as described https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html[here], you can use these values to connect the client with your cluster, as illustrated in the following code snippet.
+
+[source,php]
+----
+$client = ClientBuilder::create()
+                    ->setApiKey('id', 'api_key') <1>
+                    ->build();
+----
+<1> ApiKey pair of `id` and `api_key` from the create API key response.
+
 === SSL Encryption
 
 Configuring SSL is a little more complex.  You need to identify if your certificate has been signed by a public

phpstan-src-71.neon

@@ -6,3 +6,6 @@ parameters:
         - '#Variable (.*) in isset\(\) always exists and is not nullable.#'
         - '#Constant JSON_THROW_ON_ERROR not found#'
         - '#class JsonException#'
+        -
+            message: '#is not subtype of Throwable#'
+            path: %currentWorkingDirectory%/src/Elasticsearch/ClientBuilder.php

phpstan-src.neon

@@ -4,3 +4,6 @@ parameters:
         # nullable types are missing everywhere
         # this should be removed and fixed in the code later
         - '#Variable (.*) in isset\(\) always exists and is not nullable.#'
+        -
+            message: '#is not subtype of Throwable#'
+            path: %currentWorkingDirectory%/src/Elasticsearch/ClientBuilder.php

src/Elasticsearch/ClientBuilder.php

@@ -6,6 +6,8 @@
 
 use Elasticsearch\Common\Exceptions\InvalidArgumentException;
 use Elasticsearch\Common\Exceptions\RuntimeException;
+use Elasticsearch\Common\Exceptions\ElasticCloudIdParseException;
+use Elasticsearch\Common\Exceptions\AuthenticationConfigException;
 use Elasticsearch\ConnectionPool\AbstractConnectionPool;
 use Elasticsearch\ConnectionPool\Selectors\RoundRobinSelector;
 use Elasticsearch\ConnectionPool\Selectors\SelectorInterface;
@@ -330,6 +332,82 @@ public function setHosts(array $hosts): ClientBuilder
         return $this;
     }
 
+    /**
+     * Set the APIKey Pair, consiting of the API Id and the ApiKey of the Response from /_security/api_key
+     *
+     * @link https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html
+     *
+     * @throws Elasticsearch\Common\Exceptions\AuthenticationConfigException
+     */
+    public function setApiKey(string $id, string $apiKey): ClientBuilder
+    {
+        if (isset($this->connectionParams['client']['curl'][CURLOPT_HTTPAUTH]) === true) {
+            throw new AuthenticationConfigException("You can't use APIKey - and Basic Authenication together.");
+        }
+
+        $this->connectionParams['client']['headers']['Authorization'] = [
+            'ApiKey ' . base64_encode($id . ':' . $apiKey)
+        ];
+
+        return $this;
+    }
+
+    /**
+     * Set the APIKey Pair, consiting of the API Id and the ApiKey of the Response from /_security/api_key
+     *
+     * @param string $username
+     * @param string $password
+     *
+     * @throws Elasticsearch\Common\Exceptions\AuthenticationConfigException
+     */
+    public function setBasicAuthentication(string $username, string $password): ClientBuilder
+    {
+        if (isset($this->connectionParams['client']['headers']['Authorization']) === true) {
+            throw new AuthenticationConfigException("You can't use APIKey - and Basic Authenication together.");
+        }
+
+        if (isset($this->connectionParams['client']['curl']) === false) {
+            $this->connectionParams['client']['curl'] = [];
+        }
+
+        $this->connectionParams['client']['curl'] += [
+            CURLOPT_HTTPAUTH => CURLAUTH_BASIC,
+            CURLOPT_USERPWD  => $username.':'.$password
+        ];
+
+        return $this;
+    }
+
+    /**
+     * Set Elastic Cloud ID to connect to Elastic Cloud
+     *
+     * @link  https://elastic.co/cloud
+     *
+     * @param string $cloudId
+     */
+    public function setElasticCloudId(string $cloudId): ClientBuilder
+    {
+        // Register the Hosts array
+        $this->setHosts([
+            [
+                'host'   => $this->parseElasticCloudId($cloudId),
+                'port'   => '',
+                'scheme' => 'https',
+            ]
+        ]);
+
+        // Merge best practices for the connection
+        $this->setConnectionParams([
+            'client' => [
+                'curl' => [
+                    CURLOPT_ENCODING => 1,
+                ],
+            ]
+        ]);
+
+        return $this;
+    }
+
     public function setConnectionParams(array $params): ClientBuilder
     {
         $this->connectionParams = $params;
@@ -565,6 +643,7 @@ private function buildConnectionsFromHosts(array $hosts): array
                 $this->logger->error("Could not parse host: ".print_r($host, true));
                 throw new RuntimeException("Could not parse host: ".print_r($host, true));
             }
+
             $connections[] = $this->connectionFactory->create($host);
         }
 
@@ -616,4 +695,26 @@ private function prependMissingScheme(string $host): string
 
         return $host;
     }
+
+    /**
+     * Parse the Elastic Cloud Params from the CloudId
+     *
+     * @param string $cloudId
+     *
+     * @return string
+     *
+     * @throws ElasticCloudIdParseException
+     */
+    private function parseElasticCloudId(string $cloudId): string
+    {
+        try {
+            list($name, $encoded) = explode(':', $cloudId);
+            list($uri, $uuids)    = explode('$', base64_decode($encoded));
+            list($es,)            = explode(':', $uuids);
+
+            return $es . '.' . $uri;
+        } catch (\Throwable $t) {
+            throw new ElasticCloudIdParseException('could not parse the Cloud ID:' . $cloudId);
+        }
+    }
 }

src/Elasticsearch/Common/Exceptions/AuthenticationConfigException.php

@@ -0,0 +1,21 @@
+<?php
+declare(strict_types = 1);
+
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information
+
+namespace Elasticsearch\Common\Exceptions;
+
+/**
+ * AuthenticationConfigException
+ *
+ * @category Elasticsearch
+ * @package  Elasticsearch\Common\Exceptions
+ * @author   Philip Krauss <[email protected]>
+ * @license  http://www.apache.org/licenses/LICENSE-2.0 Apache2
+ * @link     http://elastic.co
+ */
+class AuthenticationConfigException extends \RuntimeException implements ElasticsearchException
+{
+}

src/Elasticsearch/Common/Exceptions/ElasticCloudIdParseException.php

@@ -0,0 +1,20 @@
+<?php declare(strict_types = 1);
+
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information
+
+namespace Elasticsearch\Common\Exceptions;
+
+/**
+ * RuntimeException
+ *
+ * @category Elasticsearch
+ * @package  Elasticsearch\Common\Exceptions
+ * @author   Philip Krauss <[email protected]>
+ * @license  http://www.apache.org/licenses/LICENSE-2.0 Apache2
+ * @link     http://elastic.co
+ */
+class ElasticCloudIdParseException extends \RuntimeException implements ElasticsearchException
+{
+}

src/Elasticsearch/Connections/Connection.php

@@ -129,7 +129,11 @@ public function __construct(
             $this->transportSchema = $hostDetails['scheme'];
         }
 
-        if (isset($hostDetails['user']) && isset($hostDetails['pass'])) {
+        // Only Set the Basic if API Key is not set and setBasicAuthentication was not called prior
+        if (isset($connectionParams['client']['headers']['Authorization']) === false
+                && isset($connectionParams['client']['curl'][CURLOPT_HTTPAUTH]) === false
+                && isset($hostDetails['user'])
+                && isset($hostDetails['pass'])) {
             $connectionParams['client']['curl'][CURLOPT_HTTPAUTH] = CURLAUTH_BASIC;
             $connectionParams['client']['curl'][CURLOPT_USERPWD] = $hostDetails['user'].':'.$hostDetails['pass'];
         }