Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 615 lines (526 sloc) 12.664 kB
72fb2e5 modified readmy
Ioseb Dzmanashvili authored
1 URI Template PHP Extension
0dc4c8c @ioseb Initial commit
authored
2 ============
3
72fb2e5 modified readmy
Ioseb Dzmanashvili authored
4 PHP extension implementation of RFC-6570 in C - http://tools.ietf.org/html/rfc6570
5
b964807 added more examples in readmy
Ioseb Dzmanashvili authored
6 Basic usage
7 -----------
8
9 Substituting query parameters:
10
7bd687e modified readmy
Ioseb Dzmanashvili authored
11 ```php
cbecf56 modified API and adjusted unit tests
Ioseb Dzmanashvili authored
12 <?php
13 $data = array(
14 "query" => "mycelium",
15 "number" => 100
16 );
72fb2e5 modified readmy
Ioseb Dzmanashvili authored
17
b964807 added more examples in readmy
Ioseb Dzmanashvili authored
18 $uri = uri_template('http://www.example.com/foo{?query,number}', $data);
19 ?>
20 ```
21
22 This will result to following URI:
23
24 http://www.example.com/foo?query=mycelium&number=100
25
35b20df added more examples to readme
Ioseb Dzmanashvili authored
26 Capturing Execution State
27 -------------------------
28
29 uri_template(...) function supports third optional parameter for capturing URI template parsing and processing state. Sometimes it's handy to see how template was parsed. Example below demonstrates usage of this parameter:
30
31 ```php
32 <?php
33 $data = array(
34 "id" => array("person","albums"),
35 "token" => "12345",
36 "fields" => array("id", "name", "picture"),
37 );
38
39 $tpl = "{/id*}{?fields,token}";
40 uri_template($tpl, $data, $result);
41 ?>
42 ```
43
44 After executing example code above $result variable will have following structure:
45
46 ```php
47 <?php
48 array (
49 'result' => '/person/albums?fields=id,name,picture&token=12345',
50 'state' => 0,
51 'expressions' => array (
52 0 => array (
53 'op' => '/',
54 'sep' => '/',
55 'ifemp' => '',
56 'allow' => false,
57 'named' => false,
58 'error' => false,
59 'vars' => array (
60 0 => array (
61 'name' => 'id',
62 'length' => 0,
63 'explode' => true,
64 ),
65 ),
66 ),
67 1 => array (
68 'op' => '?',
69 'sep' => '&',
70 'ifemp' => '=',
71 'allow' => false,
72 'named' => true,
73 'error' => false,
74 'vars' => array (
75 0 => array (
76 'name' => 'fields',
77 'length' => 0,
78 'explode' => false,
79 ),
80 1 => array (
81 'name' => 'token',
82 'length' => 0,
83 'explode' => false,
84 ),
85 ),
86 ),
87 ),
88 )
89 ?>
90 ```
91
b964807 added more examples in readmy
Ioseb Dzmanashvili authored
92 Detailed examples
93 -----------------
94
c39106f fixed readme
Ioseb Dzmanashvili authored
95 All following subsections will rely on the data array shown below:
b964807 added more examples in readmy
Ioseb Dzmanashvili authored
96
97 ```php
98 <?php
99 $data = array(
100 'count' => array("one", "two", "three"),
101 'dom' => array("example", "com"),
102 'dub' => "me/too",
103 'hello' => "Hello World!",
104 'half' => "50%",
105 'var' => "value",
106 'who' => "fred",
107 'base' => "http://example.com/home/",
108 'path' => "/foo/bar",
109 'list' => array("red", "green", "blue"),
110 'keys' => array(
111 "semi" => ";",
112 "dot" => ".",
113 "comma" => ",",
114 ),
115 'v' => "6",
116 'x' => "1024",
117 'y' => "768",
118 'empty' => "",
119 'empty_keys' => array(),
120 'undef' => null,
121 );
122 ?>
123 ```
124
125
126 Variable expansion
127 ------------------
128
129 For more details see [corresponding spec](http://tools.ietf.org/html/rfc6570#section-3.2.1).
130
131 ```php
132 <?php
133 $templates = array(
134 '{count}',
135 '{count*}',
136 '{/count}',
137 '{/count*}',
138 '{;count}',
139 '{;count*}',
140 '{?count}',
141 '{?count*}',
142 '{&count*}',
143 );
144
145 $uris = array();
146
147 foreach ($templates as $template) {
148 $uris[$template] = uri_template($template, $data);
149 }
150
151 var_export($uris);
152 ?>
153 ```
154
155 This will result to following URI array:
156
157 ```php
158 <?php
159 array (
160 '{count}' => 'one,two,three',
161 '{count*}' => 'one,two,three',
162 '{/count}' => '/one,two,three',
163 '{/count*}' => '/one/two/three',
164 '{;count}' => ';count=one,two,three',
165 '{;count*}' => ';count=one;count=two;count=three',
166 '{?count}' => '?count=one,two,three',
167 '{?count*}' => '?count=one&count=two&count=three',
168 '{&count*}' => '&count=one&count=two&count=three',
169 )
170 ?>
171 ```
172
173 Simple String Expansion: {var}
174 ------------------------------
175
176 For more details see [corresponding spec](http://tools.ietf.org/html/rfc6570#section-3.2.2).
177
c39106f fixed readme
Ioseb Dzmanashvili authored
178 ```php
b964807 added more examples in readmy
Ioseb Dzmanashvili authored
179 <?php
180 $templates = array(
181 "{var}",
182 "{hello}",
183 "{half}",
184 "O{empty}X",
185 "O{undef}X",
186 "{x,y}",
187 "{x,hello,y}",
188 "?{x,empty}",
189 "?{x,undef}",
190 "?{undef,y}",
191 "{var:3}",
192 "{var:30}",
193 "{list}",
194 "{list*}",
195 "{keys}",
196 "{keys*}"
197 );
198
199 $uris = array();
200
201 foreach ($templates as $template) {
202 $uris[$template] = uri_template($template, $data);
203 }
cbecf56 modified API and adjusted unit tests
Ioseb Dzmanashvili authored
204
b964807 added more examples in readmy
Ioseb Dzmanashvili authored
205 var_export($uris);
206 ?>
207 ```
208
209 This will result to following URI array:
210
211 ```php
212 <?php
213 array (
214 '{var}' => 'value',
215 '{hello}' => 'Hello%20World%21',
216 '{half}' => '50%25',
217 'O{empty}X' => 'OX',
218 'O{undef}X' => 'OX',
219 '{x,y}' => '1024,768',
220 '{x,hello,y}' => '1024,Hello%20World%21,768',
221 '?{x,empty}' => '?1024,',
222 '?{x,undef}' => '?1024',
223 '?{undef,y}' => '?768',
224 '{var:3}' => 'val',
225 '{var:30}' => 'value',
226 '{list}' => 'red,green,blue',
227 '{list*}' => 'red,green,blue',
228 '{keys}' => 'semi,%3B,dot,.,comma,%2C',
229 '{keys*}' => 'semi=%3B,dot=.,comma=%2C',
230 )
231 ?>
c39106f fixed readme
Ioseb Dzmanashvili authored
232 ```
233
234 Reserved Expansion: {+var}
235 --------------------------
236
666525b added more examples to readme
Ioseb Dzmanashvili authored
237 For more details see [corresponding spec](http://tools.ietf.org/html/rfc6570#section-3.2.3).
238
239 ```php
240 <?php
241 $templates = array(
242 "{+var}",
243 "{+hello}",
244 "{+half}",
245 "{base}index",
246 "{+base}index",
247 "O{+empty}X",
248 "O{+undef}X",
249 "{+path}/here",
250 "here?ref={+path}",
251 "up{+path}{var}/here",
252 "{+x,hello,y}",
253 "{+path,x}/here",
254 "{+path:6}/here",
255 "{+list}",
256 "{+list*}",
257 "{+keys}",
258 "{+keys*}"
259 );
260
261 $uris = array();
262
263 foreach ($templates as $template) {
264 $uris[$template] = uri_template($template, $data);
265 }
266
267 var_export($uris);
268 ?>
269 ```
270
271 This will result to following URI array:
272
273 ```php
274 <?php
275 array (
276 '{+var}' => 'value',
277 '{+hello}' => 'Hello%20World!',
278 '{+half}' => '50%25',
279 '{base}index' => 'http%3A%2F%2Fexample.com%2Fhome%2Findex',
280 '{+base}index' => 'http://example.com/home/index',
281 'O{+empty}X' => 'OX',
282 'O{+undef}X' => 'OX',
283 '{+path}/here' => '/foo/bar/here',
284 'here?ref={+path}' => 'here?ref=/foo/bar',
285 'up{+path}{var}/here' => 'up/foo/barvalue/here',
286 '{+x,hello,y}' => '1024,Hello%20World!,768',
287 '{+path,x}/here' => '/foo/bar,1024/here',
288 '{+path:6}/here' => '/foo/b/here',
289 '{+list}' => 'red,green,blue',
290 '{+list*}' => 'red,green,blue',
291 '{+keys}' => 'semi,;,dot,.,comma,,',
292 '{+keys*}' => 'semi=;,dot=.,comma=,',
293 )
294 ?>
295 ```
296
297 Fragment Expansion: {#var}
298 --------------------------
299
300 For more details see [corresponding spec](http://tools.ietf.org/html/rfc6570#section-3.2.4).
301
302 ```php
303 <?php
304 $templates = array(
305 "{#var}",
306 "{#hello}",
307 "{#half}",
308 "foo{#empty}",
309 "foo{#undef}",
310 "{#x,hello,y}",
311 "{#path,x}/here",
312 "{#path:6}/here",
313 "{#list}",
314 "{#list*}",
315 "{#keys}",
316 "{#keys*}"
317 );
318
319 $uris = array();
320
321 foreach ($templates as $template) {
322 $uris[$template] = uri_template($template, $data);
323 }
324
325 var_export($uris);
326 ?>
327 ```
328
329 This will result to following URI array:
330
331 ```php
332 <?php
333 array(
334 "{#var}" => "#value",
335 "{#hello}" => "#Hello%20World!",
336 "{#half}" => "#50%25",
337 "foo{#empty}" => "foo#",
338 "foo{#undef}" => "foo",
339 "{#x,hello,y}" => "#1024,Hello%20World!,768",
340 "{#path,x}/here" => "#/foo/bar,1024/here",
341 "{#path:6}/here" => "#/foo/b/here",
342 "{#list}" => "#red,green,blue",
343 "{#list*}" => "#red,green,blue",
344 "{#keys}" => "#semi,;,dot,.,comma,,",
345 "{#keys*}" => "#semi=;,dot=.,comma=,"
346 )
347 ?>
348 ```
349
350 Label Expansion with Dot-Prefix: {.var}
351 ---------------------------------------
352
353 For more details see [corresponding spec](http://tools.ietf.org/html/rfc6570#section-3.2.5).
354
355 ```php
356 <?php
357 $templates = array(
358 "{.who}",
359 "{.who,who}",
360 "{.half,who}",
361 "www{.dom*}",
362 "X{.var}",
363 "X{.empty}",
364 "X{.undef}",
365 "X{.var:3}",
366 "X{.list}",
367 "X{.list*}",
368 "X{.keys}",
369 "X{.keys*}",
370 "X{.empty_keys}",
371 "X{.empty_keys*}"
372 );
373
374 $uris = array();
375
376 foreach ($templates as $template) {
377 $uris[$template] = uri_template($template, $data);
378 }
379
380 var_export($uris);
381 ?>
382 ```
383
384 This will result to following URI array:
385
386 ```php
387 <?php
388 array(
389 "{.who}" => ".fred",
390 "{.who,who}" => ".fred.fred",
391 "{.half,who}" => ".50%25.fred",
392 "www{.dom*}" => "www.example.com",
393 "X{.var}" => "X.value",
394 "X{.empty}" => "X.",
395 "X{.undef}" => "X",
396 "X{.var:3}" => "X.val",
397 "X{.list}" => "X.red,green,blue",
398 "X{.list*}" => "X.red.green.blue",
399 "X{.keys}" => "X.semi,%3B,dot,.,comma,%2C",
400 "X{.keys*}" => "X.semi=%3B.dot=..comma=%2C",
401 "X{.empty_keys}" => "X",
402 "X{.empty_keys*}" => "X"
403 )
404 ?>
405 ```
406
407 Path Segment Expansion: {/var}
408 ------------------------------
409
410 For more details see [corresponding spec](http://tools.ietf.org/html/rfc6570#section-3.2.6).
411
412 ```php
413 <?php
414 $templates = array(
415 "{/who}",
416 "{/who,who}",
417 "{/half,who}",
418 "{/who,dub}",
419 "{/var}",
420 "{/var,empty}",
421 "{/var,undef}",
422 "{/var,x}/here",
423 "{/var:1,var}",
424 "{/list}",
425 "{/list*}",
426 "{/list*,path:4}",
427 "{/keys}",
428 "{/keys*}"
429 );
430
431 $uris = array();
432
433 foreach ($templates as $template) {
434 $uris[$template] = uri_template($template, $data);
435 }
436
437 var_export($uris);
438 ?>
439 ```
440
441 This will result to following URI array:
442
443 ```php
444 <?php
445 array(
446 "{/who}" => "/fred",
447 "{/who,who}" => "/fred/fred",
448 "{/half,who}" => "/50%25/fred",
449 "{/who,dub}" => "/fred/me%2Ftoo",
450 "{/var}" => "/value",
451 "{/var,empty}" => "/value/",
452 "{/var,undef}" => "/value",
453 "{/var,x}/here" => "/value/1024/here",
454 "{/var:1,var}" => "/v/value",
455 "{/list}" => "/red,green,blue",
456 "{/list*}" => "/red/green/blue",
457 "{/list*,path:4}" => "/red/green/blue/%2Ffoo",
458 "{/keys}" => "/semi,%3B,dot,.,comma,%2C",
459 "{/keys*}" => "/semi=%3B/dot=./comma=%2C"
460 )
461 ?>
462 ```
463
464 Path-Style Parameter Expansion: {;var}
465 --------------------------------------
466
467 For more details see [corresponding spec](http://tools.ietf.org/html/rfc6570#section-3.2.7).
468
469 ```php
470 <?php
471 $templates = array(
472 "{;who}",
473 "{;half}",
474 "{;empty}",
475 "{;v,empty,who}",
476 "{;v,bar,who}",
477 "{;x,y}",
478 "{;x,y,empty}",
479 "{;x,y,undef}",
480 "{;hello:5}",
481 "{;list}",
482 "{;list*}",
483 "{;keys}",
484 "{;keys*}"
485 );
486
487 $uris = array();
488
489 foreach ($templates as $template) {
490 $uris[$template] = uri_template($template, $data);
491 }
492
493 var_export($uris);
494 ?>
495 ```
496
497 This will result to following URI array:
498
499 ```php
500 <?php
501 array(
502 "{;who}" => ";who=fred",
503 "{;half}" => ";half=50%25",
504 "{;empty}" => ";empty",
505 "{;v,empty,who}" => ";v=6;empty;who=fred",
506 "{;v,bar,who}" => ";v=6;who=fred",
507 "{;x,y}" => ";x=1024;y=768",
508 "{;x,y,empty}" => ";x=1024;y=768;empty",
509 "{;x,y,undef}" => ";x=1024;y=768",
510 "{;hello:5}" => ";hello=Hello",
511 "{;list}" => ";list=red,green,blue",
512 "{;list*}" => ";list=red;list=green;list=blue",
513 "{;keys}" => ";keys=semi,%3B,dot,.,comma,%2C",
514 "{;keys*}" => ";semi=%3B;dot=.;comma=%2C"
515 )
516 ?>
517 ```
518
519 Form-Style Query Expansion: {?var}
520 ----------------------------------
521
522 For more details see [corresponding spec](http://tools.ietf.org/html/rfc6570#section-3.2.8).
523
524 ```php
525 <?php
526 $templates = array(
527 "{?who}",
528 "{?half}",
529 "{?x,y}",
530 "{?x,y,empty}",
531 "{?x,y,undef}",
532 "{?var:3}",
533 "{?list}",
534 "{?list*}",
535 "{?keys}",
536 "{?keys*}"
537 );
538
539 $uris = array();
540
541 foreach ($templates as $template) {
542 $uris[$template] = uri_template($template, $data);
543 }
544
545 var_export($uris);
546 ?>
547 ```
548
549 This will result to following URI array:
550
551 ```php
552 <?php
553 array(
554 "{?who}" => "?who=fred",
555 "{?half}" => "?half=50%25",
556 "{?x,y}" => "?x=1024&y=768",
557 "{?x,y,empty}" => "?x=1024&y=768&empty=",
558 "{?x,y,undef}" => "?x=1024&y=768",
559 "{?var:3}" => "?var=val",
560 "{?list}" => "?list=red,green,blue",
561 "{?list*}" => "?list=red&list=green&list=blue",
562 "{?keys}" => "?keys=semi,%3B,dot,.,comma,%2C",
563 "{?keys*}" => "?semi=%3B&dot=.&comma=%2C"
564 )
565 ?>
566 ```
567
568 Form-Style Query Continuation: {&var}
569 -------------------------------------
570
571 For more details see [corresponding spec](http://tools.ietf.org/html/rfc6570#section-3.2.9).
572
573 ```php
574 <?php
575 $templates = array(
576 "{&who}",
577 "{&half}",
578 "?fixed=yes{&x}",
579 "{&x,y,empty}",
580 "{&x,y,undef}",
581 "{&var:3}",
582 "{&list}",
583 "{&list*}",
584 "{&keys}",
585 "{&keys*}"
586 );
587
588 $uris = array();
589
590 foreach ($templates as $template) {
591 $uris[$template] = uri_template($template, $data);
592 }
593
594 var_export($uris);
595 ?>
596 ```
597
598 This will result to following URI array:
599
600 ```php
601 <?php
602 array(
603 "{&who}" => "&who=fred",
604 "{&half}" => "&half=50%25",
605 "?fixed=yes{&x}" => "?fixed=yes&x=1024",
606 "{&x,y,empty}" => "&x=1024&y=768&empty=",
607 "{&x,y,undef}" => "&x=1024&y=768",
608 "{&var:3}" => "&var=val",
609 "{&list}" => "&list=red,green,blue",
610 "{&list*}" => "&list=red&list=green&list=blue",
611 "{&keys}" => "&keys=semi,%3B,dot,.,comma,%2C",
612 "{&keys*}" => "&semi=%3B&dot=.&comma=%2C"
613 )
614 ?>
615 ```
Something went wrong with that request. Please try again.