diff --git a/docs/configuration.rst b/docs/configuration.rst index 822ae8e9c2..9401dccb10 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -188,9 +188,9 @@ Options Description ``region`` Region name (e.g., 'us-east-1', 'us-west-1', 'us-west-2', 'eu-west-1', etc.). See :ref:`specify_region`. -``scheme`` URI Scheme of the base URL (e.g.. 'https', 'http') used when base_url is not supplied. +``scheme`` URI Scheme of the base URL (e.g.. 'https', 'http') used when endpoint is not supplied. -``base_url`` Allows you to specify a custom endpoint instead of have the SDK build one automatically from +``endpoint`` Allows you to specify a custom endpoint instead of have the SDK build one automatically from the region and scheme. ``signature`` Overrides the signature used by the client. Clients will always choose an appropriate default @@ -263,7 +263,7 @@ Here's an example of creating an Amazon DynamoDB client that uses the ``us-west- Setting a custom endpoint ~~~~~~~~~~~~~~~~~~~~~~~~~ -You can specify a completely customized endpoint for a client using the client's ``base_url`` option. If the client you +You can specify a completely customized endpoint for a client using the client's ``endpoint`` option. If the client you are using requires a region, then must still specify the name of the region using the ``region`` option. Setting a custom endpoint can be useful if you're using a mock web server that emulates a web service, you're testing against a private beta endpoint, or you are trying to a use a new region not yet supported by the SDK. @@ -278,7 +278,7 @@ Here's an example of creating an Amazon DynamoDB client that uses a completely c // Create a client that that contacts a completely customized base URL $client = DynamoDbClient::factory(array( - 'base_url' => 'http://my-custom-url', + 'endpoint' => 'http://my-custom-url', 'region' => 'my-region-1', 'key' => 'abc', 'secret' => '123' diff --git a/docs/service-cloudsearchdomain.rst b/docs/service-cloudsearchdomain.rst index 73b9b71be6..6b1d447090 100644 --- a/docs/service-cloudsearchdomain.rst +++ b/docs/service-cloudsearchdomain.rst @@ -23,11 +23,11 @@ Similar to the way other service clients are used, you can instantiate the ``Clo $client = CloudSearchDomainClient::factory(array( 'profile' => '', - 'base_url' => '' + 'endpoint' => '' )); The ``CloudSearchDomainClient`` is unlike other clients, because it does not require you to provide a region. Instead, -you must provide the ``base_url`` option, which represents the domain's endpoint. Domain endpoints are unique to each +you must provide the ``endpoint`` option, which represents the domain's endpoint. Domain endpoints are unique to each domain, and you can get it using the `DescribeDomains operation `_ of the :doc:`Amazon CloudSearch configuration client`. @@ -49,13 +49,13 @@ all clients so that you only have to specify your settings once. // Get the client from the builder $client = $aws->get('CloudSearchDomain'); -**Note:** This assumes that your configuration file has been setup to include the ``base_url`` option for the +**Note:** This assumes that your configuration file has been setup to include the ``endpoint`` option for the CloudSearch Domain service. If it is not, you can provide it manually when calling ``get()``. .. code-block:: php $client = $aws->get('cloudsearchdomain', array( - 'base_url' => '' + 'endpoint' => '' )); For more information about configuration files, see :doc:`configuration`. diff --git a/src/Aws/CloudSearch/CloudSearchClient.php b/src/Aws/CloudSearch/CloudSearchClient.php index 9d9598241d..46aac6a55b 100644 --- a/src/Aws/CloudSearch/CloudSearchClient.php +++ b/src/Aws/CloudSearch/CloudSearchClient.php @@ -95,8 +95,8 @@ public static function factory($config = array()) */ public function getDomainClient($domainName, array $config = array()) { - // Determine the Domain client's base_url - $config['base_url'] = $this->describeDomains(array( + // Determine the Domain client's endpoint + $config['endpoint'] = $this->describeDomains(array( 'DomainNames' => array($domainName) ))->getPath('DomainStatusList/0/SearchService/Endpoint'); diff --git a/src/Aws/CloudSearchDomain/CloudSearchDomainClient.php b/src/Aws/CloudSearchDomain/CloudSearchDomainClient.php index 1d43c752f8..9feb853ab8 100644 --- a/src/Aws/CloudSearchDomain/CloudSearchDomainClient.php +++ b/src/Aws/CloudSearchDomain/CloudSearchDomainClient.php @@ -3,7 +3,6 @@ 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; @@ -26,7 +25,7 @@ class CloudSearchDomainClient extends AbstractClient /** * Factory method to create a new Amazon CloudSearch Domain client using an array of configuration options. * - * You must provide the `base_url` option for this client, but credentials and `region` are not needed. + * You must provide the `endpoint` option for this client, but credentials and `region` are not needed. * * @param array|Collection $config Client configuration data * diff --git a/src/Aws/CloudSearchDomain/CloudSearchDomainClientBuilder.php b/src/Aws/CloudSearchDomain/CloudSearchDomainClientBuilder.php index c1a0ab0500..fe5326536a 100644 --- a/src/Aws/CloudSearchDomain/CloudSearchDomainClientBuilder.php +++ b/src/Aws/CloudSearchDomain/CloudSearchDomainClientBuilder.php @@ -5,13 +5,11 @@ 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; @@ -41,18 +39,21 @@ public function build() $this->configRequirements ); - // Make sure base_url is correctly set - if (!($baseUrl = $config->get(Options::BASE_URL))) { + $endpoint = $config['endpoint'] ?: $config[Options::BASE_URL]; + + // Make sure endpoint is correctly set + if (!$endpoint) { 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, - ))); + } + + if (strpos($endpoint, 'http') !== 0) { + $endpoint = $config[Options::SCHEME] . '://' . $endpoint; + $config['endpoint'] = $endpoint; + $config[Options::BASE_URL] = $endpoint; } // Determine the region from the endpoint - $endpoint = Url::factory($config->get(Options::BASE_URL)); + $endpoint = Url::factory($endpoint); list(,$region) = explode('.', $endpoint->getHost()); $config[Options::REGION] = $config[Options::SIGNATURE_REGION] = $region; diff --git a/src/Aws/Common/Client/ClientBuilder.php b/src/Aws/Common/Client/ClientBuilder.php index 4b59bd6f03..dc03d6f17f 100644 --- a/src/Aws/Common/Client/ClientBuilder.php +++ b/src/Aws/Common/Client/ClientBuilder.php @@ -380,37 +380,8 @@ protected function updateConfigFromDescription(Collection $config) $this->setIteratorsConfig($iterators); } - // Make sure a valid region is set - $region = $config->get(Options::REGION); - $global = $description->getData('globalEndpoint'); - - if (!$global && !$region) { - throw new InvalidArgumentException( - 'A region is required when using ' . $description->getData('serviceFullName') - ); - } elseif ($global && !$region) { - $region = 'us-east-1'; - $config->set(Options::REGION, 'us-east-1'); - } - - if (!$config->get(Options::BASE_URL)) { - $endpoint = call_user_func( - $config->get('endpoint_provider'), - array( - 'scheme' => $config->get(Options::SCHEME), - 'region' => $region, - 'service' => $config->get(Options::SERVICE) - ) - ); - $config->set(Options::BASE_URL, $endpoint['endpoint']); - - // Set a signature if one was not explicitly provided. - if (!$config->hasKey(Options::SIGNATURE) - && isset($endpoint['signatureVersion']) - ) { - $config->set(Options::SIGNATURE, $endpoint['signatureVersion']); - } - } + $this->handleRegion($config); + $this->handleEndpoint($config); return $description; } @@ -475,4 +446,51 @@ protected function getCredentials(Collection $config) return $credentials; } + + private function handleRegion(Collection $config) + { + // Make sure a valid region is set + $region = $config[Options::REGION]; + $description = $config[Options::SERVICE_DESCRIPTION]; + $global = $description->getData('globalEndpoint'); + + if (!$global && !$region) { + throw new InvalidArgumentException( + 'A region is required when using ' . $description->getData('serviceFullName') + ); + } elseif ($global && !$region) { + $config[Options::REGION] = 'us-east-1'; + } + } + + private function handleEndpoint(Collection $config) + { + // Alias "endpoint" with "base_url" for forwards compatibility. + if ($config['endpoint']) { + $config[Options::BASE_URL] = $config['endpoint']; + return; + } + + if ($config[Options::BASE_URL]) { + return; + } + + $endpoint = call_user_func( + $config['endpoint_provider'], + array( + 'scheme' => $config[Options::SCHEME], + 'region' => $config[Options::REGION], + 'service' => $config[Options::SERVICE] + ) + ); + + $config[Options::BASE_URL] = $endpoint['endpoint']; + + // Set a signature if one was not explicitly provided. + if (!$config->hasKey(Options::SIGNATURE) + && isset($endpoint['signatureVersion']) + ) { + $config->set(Options::SIGNATURE, $endpoint['signatureVersion']); + } + } } diff --git a/src/Aws/Common/Client/DefaultClient.php b/src/Aws/Common/Client/DefaultClient.php index 1dc276d3cc..277f088069 100644 --- a/src/Aws/Common/Client/DefaultClient.php +++ b/src/Aws/Common/Client/DefaultClient.php @@ -42,8 +42,8 @@ class DefaultClient extends AbstractClient * Region and endpoint options (Some services do not require a region while others do. Check the service specific user guide documentation for details): * * - region: Region name (e.g. 'us-east-1', 'us-west-1', 'us-west-2', 'eu-west-1', etc...) - * - scheme: URI Scheme of the base URL (e.g. 'https', 'http') used when base_url is not supplied - * - base_url: Allows you to specify a custom endpoint instead of building one from the region and scheme + * - scheme: URI Scheme of the base URL (e.g. 'https', 'http') used when endpoint is not supplied + * - endpoint: Allows you to specify a custom endpoint instead of building one from the region and scheme * * Generic client options: *