spaces.php

aws/Aws/Endpoint/EndpointProvider.php

@@ -0,0 +1,96 @@
+<?php
+namespace Aws\Endpoint;
+
+use Aws\Exception\UnresolvedEndpointException;
+
+/**
+ * Endpoint providers.
+ *
+ * An endpoint provider is a function that accepts a hash of endpoint options,
+ * including but not limited to "service" and "region" key value pairs. The
+ * endpoint provider function returns a hash of endpoint data, which MUST
+ * include an "endpoint" key value pair that represents the resolved endpoint
+ * or NULL if an endpoint cannot be determined.
+ *
+ * You can wrap your calls to an endpoint provider with the
+ * {@see EndpointProvider::resolve} function to ensure that an endpoint hash is
+ * created. If an endpoint hash is not created, then the resolve() function
+ * will throw an {@see Aws\Exception\UnresolvedEndpointException}.
+ *
+ *     use Aws\Endpoint\EndpointProvider;
+ *     $provider = EndpointProvider::defaultProvider();
+ *     // Returns an array or NULL.
+ *     $endpoint = $provider(['service' => 'ec2', 'region' => 'us-west-2']);
+ *     // Returns an endpoint array or throws.
+ *     $endpoint = EndpointProvider::resolve($provider, [
+ *         'service' => 'ec2',
+ *         'region'  => 'us-west-2'
+ *     ]);
+ *
+ * You can compose multiple providers into a single provider using
+ * {@see Aws\or_chain}. This function accepts providers as arguments and
+ * returns a new function that will invoke each provider until a non-null value
+ * is returned.
+ *
+ *     $a = function (array $args) {
+ *         if ($args['region'] === 'my-test-region') {
+ *             return ['endpoint' => 'http://localhost:123/api'];
+ *         }
+ *     };
+ *     $b = EndpointProvider::defaultProvider();
+ *     $c = \Aws\or_chain($a, $b);
+ *     $config = ['service' => 'ec2', 'region' => 'my-test-region'];
+ *     $res = $c($config);  // $a handles this.
+ *     $config['region'] = 'us-west-2';
+ *     $res = $c($config); // $b handles this.
+ */
+class EndpointProvider
+{
+    /**
+     * Resolves and endpoint provider and ensures a non-null return value.
+     *
+     * @param callable $provider Provider function to invoke.
+     * @param array    $args     Endpoint arguments to pass to the provider.
+     *
+     * @return array
+     * @throws UnresolvedEndpointException
+     */
+    public static function resolve(callable $provider, array $args = [])
+    {
+        $result = $provider($args);
+        if (is_array($result)) {
+            return $result;
+        }
+
+        throw new UnresolvedEndpointException(
+            'Unable to resolve an endpoint using the provider arguments: '
+            . json_encode($args) . '. Note: you can provide an "endpoint" '
+            . 'option to a client constructor to bypass invoking an endpoint '
+            . 'provider.');
+    }
+
+    /**
+     * Creates and returns the default SDK endpoint provider.
+     *
+     * @deprecated Use an instance of \Aws\Endpoint\Partition instead.
+     *
+     * @return callable
+     */
+    public static function defaultProvider()
+    {
+        return PartitionEndpointProvider::defaultProvider();
+    }
+
+    /**
+     * Creates and returns an endpoint provider that uses patterns from an
+     * array.
+     *
+     * @param array $patterns Endpoint patterns
+     *
+     * @return callable
+     */
+    public static function patterns(array $patterns)
+    {
+        return new PatternEndpointProvider($patterns);
+    }
+}