1<?php
2namespace Aws\Endpoint;
3
4use Aws\Exception\UnresolvedEndpointException;
5
6/**
7 * Endpoint providers.
8 *
9 * An endpoint provider is a function that accepts a hash of endpoint options,
10 * including but not limited to "service" and "region" key value pairs. The
11 * endpoint provider function returns a hash of endpoint data, which MUST
12 * include an "endpoint" key value pair that represents the resolved endpoint
13 * or NULL if an endpoint cannot be determined.
14 *
15 * You can wrap your calls to an endpoint provider with the
16 * {@see EndpointProvider::resolve} function to ensure that an endpoint hash is
17 * created. If an endpoint hash is not created, then the resolve() function
18 * will throw an {@see Aws\Exception\UnresolvedEndpointException}.
19 *
20 *     use Aws\Endpoint\EndpointProvider;
21 *     $provider = EndpointProvider::defaultProvider();
22 *     // Returns an array or NULL.
23 *     $endpoint = $provider(['service' => 'ec2', 'region' => 'us-west-2']);
24 *     // Returns an endpoint array or throws.
25 *     $endpoint = EndpointProvider::resolve($provider, [
26 *         'service' => 'ec2',
27 *         'region'  => 'us-west-2'
28 *     ]);
29 *
30 * You can compose multiple providers into a single provider using
31 * {@see Aws\or_chain}. This function accepts providers as arguments and
32 * returns a new function that will invoke each provider until a non-null value
33 * is returned.
34 *
35 *     $a = function (array $args) {
36 *         if ($args['region'] === 'my-test-region') {
37 *             return ['endpoint' => 'http://localhost:123/api'];
38 *         }
39 *     };
40 *     $b = EndpointProvider::defaultProvider();
41 *     $c = \Aws\or_chain($a, $b);
42 *     $config = ['service' => 'ec2', 'region' => 'my-test-region'];
43 *     $res = $c($config);  // $a handles this.
44 *     $config['region'] = 'us-west-2';
45 *     $res = $c($config); // $b handles this.
46 */
47class EndpointProvider
48{
49    /**
50     * Resolves and endpoint provider and ensures a non-null return value.
51     *
52     * @param callable $provider Provider function to invoke.
53     * @param array    $args     Endpoint arguments to pass to the provider.
54     *
55     * @return array
56     * @throws UnresolvedEndpointException
57     */
58    public static function resolve(callable $provider, array $args = [])
59    {
60        $result = $provider($args);
61        if (is_array($result)) {
62            return $result;
63        }
64
65        throw new UnresolvedEndpointException(
66            'Unable to resolve an endpoint using the provider arguments: '
67            . json_encode($args) . '. Note: you can provide an "endpoint" '
68            . 'option to a client constructor to bypass invoking an endpoint '
69            . 'provider.');
70    }
71
72    /**
73     * Creates and returns the default SDK endpoint provider.
74     *
75     * @deprecated Use an instance of \Aws\Endpoint\Partition instead.
76     *
77     * @return callable
78     */
79    public static function defaultProvider()
80    {
81        return PartitionEndpointProvider::defaultProvider();
82    }
83
84    /**
85     * Creates and returns an endpoint provider that uses patterns from an
86     * array.
87     *
88     * @param array $patterns Endpoint patterns
89     *
90     * @return callable
91     */
92    public static function patterns(array $patterns)
93    {
94        return new PatternEndpointProvider($patterns);
95    }
96}
97