media-cloud-sync / includes / sdk / google / rize / uri-template / README.md

README.md in Media Cloud Sync 1.2.8, at includes/sdk/google/rize/uri-template/README.md

250 lines 7.6 KB

Raw Download Zip

1	# PHP URI Template
2
3	This is a URI Template implementation in PHP based on [](http://tools.ietf.org/html/rfc6570RFC 6570 URI Template](http://tools.ietf.org/html/rfc6570](http://tools.ietf.org/html/rfc6570). In addition to URI expansion, it also supports URI extraction (used by [](https://github.com/googleapis/google-cloud-php-coreGoogle Cloud Core](https://github.com/googleapis/google-cloud-php-core](https://github.com/googleapis/google-cloud-php-core) and [](https://github.com/googleapis/google-cloud-phpGoogle Cloud Client Library](https://github.com/googleapis/google-cloud-php](https://github.com/googleapis/google-cloud-php)).
4
5	![CI](https://github.com/rize/UriTemplate/workflows/CI/badge.svg) [](https://packagist.org/packages/rize/uri-template![Total Downloads](https://poser.pugx.org/rize/uri-template/downloads.png)](https://packagist.org/packages/rize/uri-template](https://packagist.org/packages/rize/uri-template)
6	[](https://opencollective.com/rize-uri-template![Financial Contributors on Open Collective](https://opencollective.com/rize-uri-template/all/badge.svg?label=financial+contributors)](https://opencollective.com/rize-uri-template](https://opencollective.com/rize-uri-template)
7
8	* [](https://github.com/rezigned/uri-template.jsNode.js/Javascript](https://github.com/rezigned/uri-template.js](https://github.com/rezigned/uri-template.js) URI Template
9
10	## Usage
11
12	### Expansion
13
14	A very simple usage (string expansion).
15
16	```php
17	<?php
18
19	use Rize\UriTemplate;
20
21	$uri = new UriTemplate();
22	$uri->expand('/{username}/profile', ['username' => 'john']);
23
24	>> '/john/profile'
25	```
26
27	`Rize\UriTemplate` supports all `Expression Types` and `Levels` specified by RFC6570.
28
29	```php
30	<?php
31
32	use Rize\UriTemplate;
33
34	$uri = new UriTemplate();
35	$uri->expand('/search/{term:1}/{term}/{?q*,limit}', [
36	'term' => 'john',
37	'q' => ['a', 'b'],
38	'limit' => 10,
39	])
40
41	>> '/search/j/john/?q=a&q=b&limit=10'
42	```
43
44	#### `/` Path segment expansion
45
46	```php
47	<?php
48
49	use Rize\UriTemplate;
50
51	$uri = new UriTemplate();
52	$uri->expand('http://{host}{/segments}/{file}{.extensions}', [
53	'host' => 'www.host.com',
54	'segments' => ['path', 'to', 'a'],
55	'file' => 'file',
56	'extensions' => ['x', 'y'],
57	]);
58
59	>> 'http://www.host.com/path/to/a/file.x.y'
60	```
61
62	`Rize\UriTemplate` accepts `base-uri` as a 1st argument and `default params` as a 2nd argument. This is very useful when you're working with API endpoint.
63
64	Take a look at real world example.
65
66	```php
67	<?php
68
69	use Rize\UriTemplate;
70
71	$uri = new UriTemplate('https://api.twitter.com/{version}', ['version' => 1.1]);
72	$uri->expand('/statuses/show/{id}.json', ['id' => '210462857140252672']);
73
74	>> https://api.twitter.com/1.1/statuses/show/210462857140252672.json
75	```
76
77	### Extraction
78
79	It also supports URI Extraction (extract all variables from URI). Let's take a look at the example.
80
81	```php
82	<?php
83
84	use Rize\UriTemplate;
85
86	$uri = new UriTemplate('https://api.twitter.com/{version}', ['version' => 1.1]);
87
88	$params = $uri->extract('/search/{term:1}/{term}/{?q*,limit}', '/search/j/john/?q=a&q=b&limit=10');
89
90	>> print_r($params);
91	(
92	[term:1] => j
93	[term] => john
94	[q] => Array
95	(
96	[0] => a
97	[1] => b
98	)
99
100	[limit] => 10
101	)
102	```
103
104	Note that in the example above, result returned by `extract` method has an extra keys named `term:1` for `prefix` modifier. This key was added just for our convenience to access prefix data.
105
106	#### `strict` mode
107
108	```php
109	<?php
110
111	use Rize\UriTemplate;
112
113	$uri = new UriTemplate();
114	$uri->extract($template, $uri, $strict = false)
115	```
116
117	Normally `extract` method will try to extract vars from a uri even if it's partially matched. For example
118
119	```php
120	<?php
121
122	use Rize\UriTemplate;
123
124	$uri = new UriTemplate();
125	$params = $uri->extract('/{?a,b}', '/?a=1')
126
127	>> print_r($params);
128	(
129	[a] => 1
130	[b] => null
131	)
132	```
133
134	With `strict mode`, it will allow you to extract uri only when variables in template are fully matched with given uri.
135
136	Which is useful when you want to determine whether the given uri is matched against your template or not (in case you want to use it as routing service).
137
138	```php
139	<?php
140
141	use Rize\UriTemplate;
142
143	$uri = new UriTemplate();
144
145	// Note that variable `b` is absent in uri
146	$params = $uri->extract('/{?a,b}', '/?a=1', true);
147
148	>>> null
149
150	// Now we give `b` some value
151	$params = $uri->extract('/{?a,b}', '/?a=1&b=2', true);
152
153	>>> print_r($params)
154	(
155	[a] => 1
156	[b] => 2
157	)
158	```
159
160	#### Array modifier `%`
161
162	By default, RFC 6570 only has 2 types of operators `:` and `*`. This `%` array operator was added to the library because current spec can't handle array style query e.g. `list[]=a` or `key[user]=john`.
163
164	Example usage for `%` modifier
165
166	```php
167	<?php
168
169	$uri->expand('{?list%,keys%}', [
170	'list' => [
171	'a', 'b',
172	),
173	'keys' => [
174	'a' => 1,
175	'b' => 2,
176	),
177	]);
178
179	// '?list[]=a&list[]=b&keys[a]=1&keys[b]=2'
180	>> '?list%5B%5D=a&list%5B%5D=b&keys%5Ba%5D=1&keys%5Bb%5D=2'
181
182	// [] get encoded to %5B%5D i.e. '?list[]=a&list[]=b&keys[a]=1&keys[b]=2'
183	$params = $uri->extract('{?list%,keys%}', '?list%5B%5D=a&list%5B%5D=b&keys%5Ba%5D=1&keys%5Bb%5D=2', )
184
185	>> print_r($params);
186	(
187	[list] => Array
188	(
189	[0] => a
190	[1] => b
191	)
192
193	[keys] => Array
194	(
195	[a] => 1
196	[b] => 2
197	)
198	)
199	```
200
201	## Installation
202
203	Using `composer`
204
205	```
206	{
207	"require": {
208	"rize/uri-template": "~0.3"
209	}
210	}
211	```
212
213	### Changelogs
214
215	* 0.2.0 Add a new modifier `%` which allows user to use `list[]=a&list[]=b` query pattern.
216	* 0.2.1 Add nested array support for `%` modifier
217	* 0.2.5 Add strict mode support for `extract` method
218	* 0.3.0 Improve code quality + RFC3986 support for `extract` method by @Maks3w
219	* 0.3.1 Improve `extract` method to parse two or more adjacent variables separated by dot by @corleonis
220
221	## Contributors
222
223	### Code Contributors
224
225	This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].
226	<a href="https://github.com/rize/UriTemplate/graphs/contributors"><img src="https://opencollective.com/rize-uri-template/contributors.svg?width=890&button=false" /></a>
227
228	### Financial Contributors
229
230	Become a financial contributor and help us sustain our community. [[Contribute](https://opencollective.com/rize-uri-template/contribute)]
231
232	#### Individuals
233
234	<a href="https://opencollective.com/rize-uri-template"><img src="https://opencollective.com/rize-uri-template/individuals.svg?width=890"></a>
235
236	#### Organizations
237
238	Support this project with your organization. Your logo will show up here with a link to your website. [[Contribute](https://opencollective.com/rize-uri-template/contribute)]
239
240	<a href="https://opencollective.com/rize-uri-template/organization/0/website"><img src="https://opencollective.com/rize-uri-template/organization/0/avatar.svg"></a>
241	<a href="https://opencollective.com/rize-uri-template/organization/1/website"><img src="https://opencollective.com/rize-uri-template/organization/1/avatar.svg"></a>
242	<a href="https://opencollective.com/rize-uri-template/organization/2/website"><img src="https://opencollective.com/rize-uri-template/organization/2/avatar.svg"></a>
243	<a href="https://opencollective.com/rize-uri-template/organization/3/website"><img src="https://opencollective.com/rize-uri-template/organization/3/avatar.svg"></a>
244	<a href="https://opencollective.com/rize-uri-template/organization/4/website"><img src="https://opencollective.com/rize-uri-template/organization/4/avatar.svg"></a>
245	<a href="https://opencollective.com/rize-uri-template/organization/5/website"><img src="https://opencollective.com/rize-uri-template/organization/5/avatar.svg"></a>
246	<a href="https://opencollective.com/rize-uri-template/organization/6/website"><img src="https://opencollective.com/rize-uri-template/organization/6/avatar.svg"></a>
247	<a href="https://opencollective.com/rize-uri-template/organization/7/website"><img src="https://opencollective.com/rize-uri-template/organization/7/avatar.svg"></a>
248	<a href="https://opencollective.com/rize-uri-template/organization/8/website"><img src="https://opencollective.com/rize-uri-template/organization/8/avatar.svg"></a>
249	<a href="https://opencollective.com/rize-uri-template/organization/9/website"><img src="https://opencollective.com/rize-uri-template/organization/9/avatar.svg"></a>
250