Added support for the CloudSearchDomain client.

The CloudSearchDomain client can be used to search and upload documents to you CloudSearch domains.

docs/_ext/aws/__init__.py

@@ -123,7 +123,11 @@ def load_description(self, path):
 
         :param path: Path to a service description to load
         """
-        return self.__load_php(path)
+        description = self.__load_php(path)
+        if 'regions' not in description:
+            description['regions'] = {}
+
+        return description
 
     def __load_php(self, path):
         """Load a PHP script that returns an array using JSON

docs/index.rst

@@ -27,6 +27,8 @@ AWS SDK for PHP
     service-cloudfront
     service-cloudfront-20120505
     service-cloudsearch
+    service-cloudsearch-20110201
+    service-cloudsearchdomain
     service-cloudtrail
     service-cloudwatch
     service-datapipeline
@@ -119,6 +121,10 @@ Service-Specific Guides
 
   * :doc:`Using the older 2011-02-01 API version <service-cloudsearch-20110201>`
 
+* Amazon CloudSearchDomain
+
+  .. indexlinks:: CloudSearchDomain
+
 * Amazon CloudWatch
 
   .. indexlinks:: CloudWatch

docs/service-cloudsearchdomain.rst

@@ -0,0 +1,56 @@
+====================================================================================
+Amazon CloudSearch Domains
+====================================================================================
+
+This guide focuses on the AWS SDK for PHP client for Amazon CloudSearch domains. The ``CloudSearchDomainClient`` allows
+you to search and upload documents to your CloudSearch domains. This guide assumes that you have already downloaded and
+installed the AWS SDK for PHP. See :doc:`installation` for more information on getting started.
+
+Creating a client
+-----------------
+
+First you need to create a client object using one of the following techniques.
+
+Factory method
+~~~~~~~~~~~~~~
+
+Similar to the way other service clients are used, you can instantiate the ``CloudSearchDomainClient`` with the
+``Aws\CloudSearchDomain\CloudSearchDomainClient::factory()`` method.
+
+.. code-block:: php
+
+    use Aws\CloudSearchDomain\CloudSearchDomainClient;
+
+    $client = CloudSearchDomainClient::factory(array(
+        'base_url' => '<your cloudsearch domain endpoint>',
+    ));
+
+The ``CloudSearchDomainClient`` is unlike other clients, because it does not require you to provide AWS credentials.
+The only thing you need to provide is the ``base_url`` option, which represents the domain's endpoint. Domain
+endpoints are unique to each domain, and you can get it by describing your domain with the :doc:`Amazon CloudSearch
+configuration client <service-cloudsearch>`.
+
+Helper method
+~~~~~~~~~~~~~
+
+An easy way to instantiate the ``CloudSearchDomainClient`` is to use the ``CloudSearchClient::getDomainClient()``
+helper method. This method use the CloudSearch configuration API to retrieve the domain endpoint, and instantiates the
+domain client for you.
+
+.. code-block:: php
+
+    use Aws\CloudSearch\CloudSearchClient;
+
+    $configClient = CloudSearchClient::factory(array(
+        'profile' => '<profile in your aws credentials file>',
+        'region'  => '<region name>',
+    ));
+
+    $domainClient = $configClient->getDomainClient('<domain name>');
+
+    // Use the search operation
+    $result = $domainClient->search(array('query' => 'foobar'));
+    $hitCount = $result->getPath('hits/found');
+    echo "Number of Hits: {$hitCount}\n";
+
+.. apiref:: CloudSearchDomain

phpunit.xml.dist

@@ -34,6 +34,7 @@
                 <directory suffix="Exception.php">./src/Aws/CloudFormation/Exception</directory>
                 <directory suffix="Exception.php">./src/Aws/CloudFront/Exception</directory>
                 <directory suffix="Exception.php">./src/Aws/CloudSearch/Exception</directory>
+                <directory suffix="Exception.php">./src/Aws/CloudSearchDomain/Exception</directory>
                 <directory suffix="Exception.php">./src/Aws/CloudTrail/Exception</directory>
                 <directory suffix="Exception.php">./src/Aws/CloudWatch/Exception</directory>
                 <directory suffix="Exception.php">./src/Aws/DataPipeline/Exception</directory>

src/Aws/CloudSearch/CloudSearchClient.php

@@ -16,6 +16,7 @@
 
 namespace Aws\CloudSearch;
 
+use Aws\CloudSearchDomain\CloudSearchDomainClient;
 use Aws\Common\Client\AbstractClient;
 use Aws\Common\Client\ClientBuilder;
 use Aws\Common\Enum\ClientOptions as Options;
@@ -81,4 +82,22 @@ public static function factory($config = array())
             ))
             ->build();
     }
+
+    /**
+     * Create a CloudSearchDomainClient for a particular domain to do searching
+     * and document uploads.
+     *
+     * @param string $domainName Name of the domain for which to create a domain client.
+     * @param array  $config     Config options for the CloudSearchDomainClient
+     *
+     * @return CloudSearchDomainClient
+     */
+    public function getDomainClient($domainName, array $config = array())
+    {
+        $config['base_url'] = $this->describeDomains(array(
+            'DomainNames' => array($domainName)
+        ))->getPath('DomainStatusList/0/SearchService/Endpoint');
+
+        return CloudSearchDomainClient::factory($config);
+    }
 }

src/Aws/CloudSearchDomain/CloudSearchDomainClient.php

@@ -0,0 +1,64 @@
+<?php
+
+namespace Aws\CloudSearchDomain;
+
+use Aws\Common\Client\AbstractClient;
+use Aws\Common\Credentials\CredentialsInterface;
+use Aws\Common\Enum\ClientOptions as Options;
+use Aws\Common\Exception\BadMethodCallException;
+use Guzzle\Common\Collection;
+use Guzzle\Service\Resource\Model;
+
+/**
+ * Client to interact with Amazon CloudSearchDomain
+ *
+ * @method Model search(array $args = array()) {@command CloudSearchDomain Search}
+ * @method Model suggest(array $args = array()) {@command CloudSearchDomain Suggest}
+ * @method Model uploadDocuments(array $args = array()) {@command CloudSearchDomain UploadDocuments}
+ *
+ * @link http://docs.aws.amazon.com/aws-sdk-php/guide/latest/service-cloudsearchdomain.html User guide
+ * @link http://docs.aws.amazon.com/aws-sdk-php/latest/class-Aws.CloudSearchDomain.CloudSearchDomainClient.html API docs
+ */
+class CloudSearchDomainClient extends AbstractClient
+{
+    const LATEST_API_VERSION = '2013-01-01';
+
+    /**
+     * Factory method to create a new Amazon CloudSearchDomain client using an array of configuration options.
+     *
+     * You must provide the `base_url` option for this client, but credentials and `region` are not needed.
+     *
+     * @param array|Collection $config Client configuration data
+     *
+     * @return self
+     * @link http://docs.aws.amazon.com/aws-sdk-php/guide/latest/configuration.html#client-configuration-options
+     */
+    public static function factory($config = array())
+    {
+        return CloudSearchDomainClientBuilder::factory(__NAMESPACE__)
+            ->setConfig($config)
+            ->setConfigDefaults(array(
+                Options::VERSION => self::LATEST_API_VERSION,
+                Options::SERVICE_DESCRIPTION => __DIR__ . '/Resources/cloudsearchdomain-%s.php'
+            ))
+            ->build();
+    }
+
+    /**
+     * @internal
+     * @throws \Aws\Common\Exception\BadMethodCallException Do not call this method
+     */
+    public function setCredentials(CredentialsInterface $credentials)
+    {
+        throw new BadMethodCallException('The CloudSearchDomain client does not require AWS credentials.');
+    }
+
+    /**
+     * @internal
+     * @throws \Aws\Common\Exception\BadMethodCallException Do not call this method
+     */
+    public function setRegion($region)
+    {
+        throw new BadMethodCallException('You cannot change the region of a CloudSearchDomain client.');
+    }
+}

src/Aws/CloudSearchDomain/CloudSearchDomainClientBuilder.php

@@ -0,0 +1,117 @@
+<?php
+
+namespace Aws\CloudSearchDomain;
+
+use Aws\Common\Client\ClientBuilder;
+use Aws\Common\Client\ThrottlingErrorChecker;
+use Aws\Common\Client\UserAgentListener;
+use Aws\Common\Credentials\Credentials;
+use Aws\Common\Enum\ClientOptions as Options;
+use Aws\Common\Exception\ExceptionListener;
+use Aws\Common\Exception\InvalidArgumentException;
+use Aws\Common\Exception\NamespaceExceptionFactory;
+use Aws\Common\Exception\Parser\JsonQueryExceptionParser;
+use Aws\Common\Signature\SignatureV4;
+use Guzzle\Common\Collection;
+use Guzzle\Http\Url;
+use Guzzle\Plugin\Backoff\BackoffPlugin;
+use Guzzle\Plugin\Backoff\CurlBackoffStrategy;
+use Guzzle\Plugin\Backoff\ExponentialBackoffStrategy;
+use Guzzle\Plugin\Backoff\HttpBackoffStrategy;
+use Guzzle\Plugin\Backoff\TruncatedBackoffStrategy;
+use Guzzle\Service\Description\ServiceDescription;
+
+/**
+ * Builder for creating CloudSearchDomain clients
+ *
+ * @internal
+ */
+class CloudSearchDomainClientBuilder extends ClientBuilder
+{
+    protected static $commonConfigDefaults = array(
+        'scheme'           => 'https',
+        'signature.ignore' => true
+    );
+
+    public function build()
+    {
+        // Resolve configuration
+        $config = Collection::fromConfig(
+            $this->config,
+            array_merge(self::$commonConfigDefaults, $this->configDefaults),
+            $this->configRequirements
+        );
+
+        // Make sure base_url is correctly set
+        if (!($baseUrl = $config->get(Options::BASE_URL))) {
+            throw new InvalidArgumentException('You must provide the endpoint for the CloudSearch domain.');
+        } elseif (strpos($baseUrl, 'http') !== 0) {
+            $config->set(Options::BASE_URL, Url::buildUrl(array(
+                'scheme' => $config->get(Options::SCHEME),
+                'host'   => $baseUrl,
+            )));
+        }
+
+        // Create dependencies
+        $exceptionParser = new JsonQueryExceptionParser();
+        $signature = new SignatureV4();
+        $credentials = new Credentials('','');
+        $description = ServiceDescription::factory(sprintf(
+            $config->get(Options::SERVICE_DESCRIPTION),
+            $config->get(Options::VERSION)
+        ));
+
+        // Resolve backoff strategy
+        $backoff = $config->get(Options::BACKOFF);
+        if ($backoff === null) {
+            $backoff = new BackoffPlugin(
+                // Retry failed requests up to 3 times if it is determined that the request can be retried
+                new TruncatedBackoffStrategy(3,
+                    // Retry failed requests with 400-level responses due to throttling
+                    new ThrottlingErrorChecker($exceptionParser,
+                        // Retry failed requests with 500-level responses
+                        new HttpBackoffStrategy(array(500, 503, 509),
+                            // Retry failed requests due to transient network or cURL problems
+                            new CurlBackoffStrategy(null,
+                                new ExponentialBackoffStrategy()
+                            )
+                        )
+                    )
+                )
+            );
+            $config->set(Options::BACKOFF, $backoff);
+        }
+        if ($backoff) {
+            $this->addBackoffLogger($backoff, $config);
+        }
+
+        // Create client
+        $client = new CloudSearchDomainClient($credentials, $signature, $config);
+        $client->setDescription($description);
+
+        // Add exception marshaling so that more descriptive exception are thrown
+        $client->addSubscriber(new ExceptionListener(new NamespaceExceptionFactory(
+            $exceptionParser,
+            __NAMESPACE__ . '\\Exception',
+            __NAMESPACE__ . '\\Exception\\CloudSearchDomainException'
+        )));
+
+        // Add the UserAgentPlugin to append to the User-Agent header of requests
+        $client->addSubscriber(new UserAgentListener);
+
+        // Filters used for the cache plugin
+        $client->getConfig()->set(
+            'params.cache.key_filter',
+            'header=date,x-amz-date,x-amz-security-token,x-amzn-authorization'
+        );
+
+        // Disable parameter validation if needed
+        if ($config->get(Options::VALIDATION) === false) {
+            $params = $config->get('command.params') ?: array();
+            $params['command.disable_validation'] = true;
+            $config->set('command.params', $params);
+        }
+
+        return $client;
+    }
+}

src/Aws/CloudSearchDomain/Exception/CloudSearchDomainException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Aws\CloudSearchDomain\Exception;
+
+use Aws\Common\Exception\ServiceResponseException;
+
+/**
+ * Exception thrown by the CloudSearchDomain client.
+ */
+class CloudSearchDomainException extends ServiceResponseException {}