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