media-cloud-sync / includes / sdk / s3 / Aws / Api / ApiProvider.php

ApiProvider.php in Media Cloud Sync 1.4.1, at includes/sdk/s3/Aws/Api/ApiProvider.php

213 lines 7.4 KB

Raw Download Zip

1	<?php
2
3	namespace Dudlewebs\WPMCS\s3\Aws\Api;
4
5	use Dudlewebs\WPMCS\s3\Aws\Exception\UnresolvedApiException;
6	/**
7	* API providers.
8	*
9	* An API provider is a function that accepts a type, service, and version and
10	* returns an array of API data on success or NULL if no API data can be created
11	* for the provided arguments.
12	*
13	* You can wrap your calls to an API provider with the
14	* {@see ApiProvider::resolve} method to ensure that API data is created. If the
15	* API data is not created, then the resolve() method will throw a
16	* {@see Aws\Exception\UnresolvedApiException}.
17	*
18	* use Aws\Api\ApiProvider;
19	* $provider = ApiProvider::defaultProvider();
20	* // Returns an array or NULL.
21	* $data = $provider('api', 's3', '2006-03-01');
22	* // Returns an array or throws.
23	* $data = ApiProvider::resolve($provider, 'api', 'elasticfood', '2020-01-01');
24	*
25	* You can compose multiple providers into a single provider using
26	* {@see Aws\or_chain}. This method accepts providers as arguments and
27	* returns a new function that will invoke each provider until a non-null value
28	* is returned.
29	*
30	* $a = ApiProvider::filesystem(sys_get_temp_dir() . '/aws-beta-models');
31	* $b = ApiProvider::manifest();
32	*
33	* $c = \Aws\or_chain($a, $b);
34	* $data = $c('api', 'betaservice', '2015-08-08'); // $a handles this.
35	* $data = $c('api', 's3', '2006-03-01'); // $b handles this.
36	* $data = $c('api', 'invalid', '2014-12-15'); // Neither handles this.
37	*/
38	class ApiProvider
39	{
40	/** @var array A map of public API type names to their file suffix. */
41	private static $typeMap = ['api' => 'api-2', 'paginator' => 'paginators-1', 'waiter' => 'waiters-2', 'docs' => 'docs-2'];
42	/** @var array API manifest */
43	private $manifest;
44	/** @var string The directory containing service models. */
45	private $modelsDir;
46	/**
47	* Resolves an API provider and ensures a non-null return value.
48	*
49	* @param callable $provider Provider function to invoke.
50	* @param string $type Type of data ('api', 'waiter', 'paginator').
51	* @param string $service Service name.
52	* @param string $version API version.
53	*
54	* @return array
55	* @throws UnresolvedApiException
56	*/
57	public static function resolve(callable $provider, $type, $service, $version)
58	{
59	// Execute the provider and return the result, if there is one.
60	$result = $provider($type, $service, $version);
61	if (\is_array($result)) {
62	if (!isset($result['metadata']['serviceIdentifier'])) {
63	$result['metadata']['serviceIdentifier'] = $service;
64	}
65	return $result;
66	}
67	// Throw an exception with a message depending on the inputs.
68	if (!isset(self::$typeMap[$type])) {
69	$msg = "The type must be one of: " . \implode(', ', self::$typeMap);
70	} elseif ($service) {
71	$msg = "The {$service} service does not have version: {$version}.";
72	} else {
73	$msg = "You must specify a service name to retrieve its API data.";
74	}
75	throw new UnresolvedApiException($msg);
76	}
77	/**
78	* Default SDK API provider.
79	*
80	* This provider loads pre-built manifest data from the `data` directory.
81	*
82	* @return self
83	*/
84	public static function defaultProvider()
85	{
86	return new self(__DIR__ . '/../data', \Dudlewebs\WPMCS\s3\Aws\manifest());
87	}
88	/**
89	* Loads API data after resolving the version to the latest, compatible,
90	* available version based on the provided manifest data.
91	*
92	* Manifest data is essentially an associative array of service names to
93	* associative arrays of API version aliases.
94	*
95	* [
96	* ...
97	* 'ec2' => [
98	* 'latest' => '2014-10-01',
99	* '2014-10-01' => '2014-10-01',
100	* '2014-09-01' => '2014-10-01',
101	* '2014-06-15' => '2014-10-01',
102	* ...
103	* ],
104	* 'ecs' => [...],
105	* 'elasticache' => [...],
106	* ...
107	* ]
108	*
109	* @param string $dir Directory containing service models.
110	* @param array $manifest The API version manifest data.
111	*
112	* @return self
113	*/
114	public static function manifest($dir, array $manifest)
115	{
116	return new self($dir, $manifest);
117	}
118	/**
119	* Loads API data from the specified directory.
120	*
121	* If "latest" is specified as the version, this provider must glob the
122	* directory to find which is the latest available version.
123	*
124	* @param string $dir Directory containing service models.
125	*
126	* @return self
127	* @throws \InvalidArgumentException if the provided `$dir` is invalid.
128	*/
129	public static function filesystem($dir)
130	{
131	return new self($dir);
132	}
133	/**
134	* Retrieves a list of valid versions for the specified service.
135	*
136	* @param string $service Service name
137	*
138	* @return array
139	*/
140	public function getVersions($service)
141	{
142	if (!isset($this->manifest)) {
143	$this->buildVersionsList($service);
144	}
145	if (!isset($this->manifest[$service]['versions'])) {
146	return [];
147	}
148	return \array_values(\array_unique($this->manifest[$service]['versions']));
149	}
150	/**
151	* Execute the provider.
152	*
153	* @param string $type Type of data ('api', 'waiter', 'paginator').
154	* @param string $service Service name.
155	* @param string $version API version.
156	*
157	* @return array\|null
158	*/
159	public function __invoke($type, $service, $version)
160	{
161	// Resolve the type or return null.
162	if (isset(self::$typeMap[$type])) {
163	$type = self::$typeMap[$type];
164	} else {
165	return null;
166	}
167	// Resolve the version or return null.
168	if (!isset($this->manifest)) {
169	$this->buildVersionsList($service);
170	}
171	if (!isset($this->manifest[$service]['versions'][$version])) {
172	return null;
173	}
174	$version = $this->manifest[$service]['versions'][$version];
175	$path = "{$this->modelsDir}/{$service}/{$version}/{$type}.json";
176	try {
177	return \Dudlewebs\WPMCS\s3\Aws\load_compiled_json($path);
178	} catch (\InvalidArgumentException $e) {
179	return null;
180	}
181	}
182	/**
183	* @param string $modelsDir Directory containing service models.
184	* @param array $manifest The API version manifest data.
185	*/
186	private function __construct($modelsDir, ?array $manifest = null)
187	{
188	$this->manifest = $manifest;
189	$this->modelsDir = \rtrim($modelsDir, '/');
190	if (!\is_dir($this->modelsDir)) {
191	throw new \InvalidArgumentException("The specified models directory, {$modelsDir}, was not found.");
192	}
193	}
194	/**
195	* Build the versions list for the specified service by globbing the dir.
196	*/
197	private function buildVersionsList($service)
198	{
199	$dir = "{$this->modelsDir}/{$service}/";
200	if (!\is_dir($dir)) {
201	return;
202	}
203	// Get versions, remove . and .., and sort in descending order.
204	$results = \array_diff(\scandir($dir, \SCANDIR_SORT_DESCENDING), ['..', '.']);
205	if (!$results) {
206	$this->manifest[$service] = ['versions' => []];
207	} else {
208	$this->manifest[$service] = ['versions' => ['latest' => $results[0]]];
209	$this->manifest[$service]['versions'] += \array_combine($results, $results);
210	}
211	}
212	}
213