|
1 |
| -Aura.Uri |
| 1 | +Fork of Aura.Uri |
2 | 2 | ========
|
3 | 3 |
|
4 |
| -[](https://travis-ci.org/auraphp/Aura.Uri) |
| 4 | +**This repository is a fork of auraphp/Aura.Uri for internal usage.** |
5 | 5 |
|
6 |
| -The `Auri.Uri` package provides objects to help you create and manipulate URLs, |
7 |
| -including query strings and path elements. It does so by splitting up the pieces |
8 |
| -of the URL and allowing you modify them individually; you can then fetch |
9 |
| -them as a single URL string. This helps when building complex links, |
10 |
| -such as in a paged navigation system. |
11 |
| - |
12 |
| -This package is compliant with [PSR-0][], [PSR-1][], and [PSR-2][]. If you |
13 |
| -notice compliance oversights, please send a patch via pull request. |
14 |
| - |
15 |
| -[PSR-0]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md |
16 |
| -[PSR-1]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md |
17 |
| -[PSR-2]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md |
18 |
| - |
19 |
| -Getting Started |
20 |
| -=============== |
21 |
| - |
22 |
| -Instantiation |
23 |
| -------------- |
24 |
| - |
25 |
| -The easiest way to instantiate a URL object is to use the factory instance |
26 |
| -script, like so: |
27 |
| - |
28 |
| -```php |
29 |
| -<?php |
30 |
| -$url_factory = require '/path/to/Aura.Uri/scripts/instance.php'; |
31 |
| -$url = $url_factory->newCurrent(); |
32 |
| -``` |
33 |
| - |
34 |
| -Alternatively, you can add the `src/` directory to your autoloader and |
35 |
| -instantiate a URL factory object: |
36 |
| - |
37 |
| -```php |
38 |
| -<?php |
39 |
| -use Aura\Uri\Url\Factory as UrlFactory; |
40 |
| - |
41 |
| -$psl = new PublicSuffixList(require '/path/to/Aura.Uri/data/public-suffix-list.php'); |
42 |
| -$url_factory = new UrlFactory($_SERVER, $psl); |
43 |
| -$url = $url_factory->newCurrent(); |
44 |
| -``` |
45 |
| - |
46 |
| -When using the factory, you can populate the URL properties from a URL |
47 |
| -string: |
48 |
| - |
49 |
| -```php |
50 |
| -<?php |
51 |
| -$string = 'http://anonymous: [email protected]/path/to/index.php/foo/bar.xml?baz=dib#anchor'); |
52 |
| -$url = $url_factory->newInstance($string); |
53 |
| - |
54 |
| -// now the $url properties are ... |
55 |
| -// |
56 |
| -// $url->scheme => 'http' |
57 |
| -// $url->user => 'anonymous' |
58 |
| -// $url->pass => 'guest' |
59 |
| -// $url->host => Aura\Uri\Host, with these methods: |
60 |
| -// ->get() => 'example.com' |
61 |
| -// ->getSubdomain() => null |
62 |
| -// ->getRegisterableDomain() => 'example.com' |
63 |
| -// ->getPublicSuffix() => 'com' |
64 |
| -// $url->port => null |
65 |
| -// $url->path => Aura\Uri\Path, with these ArrayObject elements: |
66 |
| -// ['path', 'to', 'index.php', 'foo', 'bar'] |
67 |
| -// and this method: |
68 |
| -// ->getFormat() => '.xml' |
69 |
| -// $url->query => Aura\Uri\Query, with these ArrayObject elements: |
70 |
| -// ['baz' => 'dib'] |
71 |
| -// $url->fragment => 'anchor' |
72 |
| -``` |
73 |
| - |
74 |
| -Alternatively, you can use the factory to create a URL representing the |
75 |
| -current web request URI: |
76 |
| - |
77 |
| -```php |
78 |
| -<?php |
79 |
| -$url = $url_factory->newCurrent(); |
80 |
| -``` |
81 |
| - |
82 |
| - |
83 |
| -Manipulation |
84 |
| ------------- |
85 |
| - |
86 |
| -After we have created the URL object, we can modify the component parts, then |
87 |
| -fetch a new URL string from the modified object. |
88 |
| - |
89 |
| -```php |
90 |
| -<?php |
91 |
| -// start with a full URL |
92 |
| -$string = 'http://anonymous: [email protected]/path/to/index.php/foo/bar.xml?baz=dib#anchor'; |
93 |
| -$url = $url_factory->newInstance($string); |
94 |
| - |
95 |
| -// change to 'https://' |
96 |
| -$url->setScheme('https'); |
97 |
| - |
98 |
| -// remove the username and password |
99 |
| -$url->setUser(null); |
100 |
| -$url->setPass(null); |
101 |
| - |
102 |
| -// change the value of 'baz' from 'dib' to 'zab' |
103 |
| -$url->query->baz = 'zab'; |
104 |
| - |
105 |
| -// add a new query element called 'zim' with a value of 'gir' |
106 |
| -$url->query->zim = 'gir'; |
107 |
| - |
108 |
| -// reset the path to something else entirely. |
109 |
| -// this will additionally set the format to '.php'. |
110 |
| -$url->path->setFromString('/something/else/entirely.php'); |
111 |
| - |
112 |
| -// add another path element |
113 |
| -$url->path[] = 'another'; |
114 |
| - |
115 |
| -// get the url as a string; this will be without the scheme, host, port, |
116 |
| -// user, or pass. |
117 |
| -$new_url = $url->get(); |
118 |
| - |
119 |
| -// the $new_url string is as follows; notice how the format |
120 |
| -// is always applied to the last path-element: |
121 |
| -// /something/else/entirely/another.php?baz=zab&zim=gir#anchor |
122 |
| - |
123 |
| -// get the full url string, including scheme, host, port, user, and pass. |
124 |
| -$full_url = $url->getFull(); |
125 |
| - |
126 |
| -// the $full_url string is as follows: |
127 |
| -// https://example.com/something/else/entirely/another.php?baz=zab&zim=gir#anchor |
128 |
| -``` |
129 |
| - |
130 |
| -Public Suffix List Host Parsing |
131 |
| -=============================== |
132 |
| - |
133 |
| -Host Component Parts |
134 |
| --------------------- |
135 |
| - |
136 |
| -In addition to URL creation and manipulation, `Aura.Uri` is capable of parsing a |
137 |
| -host into its component parts, namely the host's subdomain, registerable domain, |
138 |
| -and public suffix. A host's component parts are available via properties on the |
139 |
| -Aura.Uri host object, as seen in the examples above. |
140 |
| - |
141 |
| -Public Suffix List |
142 |
| ------------------- |
143 |
| - |
144 |
| -This parsing capability is possible as a result of the [Public Suffix List][], a community |
145 |
| -resource and initiative of Mozilla. |
146 |
| - |
147 |
| -Updating the Public Suffix List |
148 |
| -------------------------------- |
149 |
| - |
150 |
| -As the Public Suffix List is both an external resource and a living document, it's |
151 |
| -important that you update your copy of the list from time to time. You can do this |
152 |
| -by executing the provided `update.php` script. |
153 |
| - |
154 |
| -`php /path/to/Aura.Uri/scripts/update.php` |
155 |
| - |
156 |
| -Executing `update.php` will retrieve the most current version of the Public Suffix |
157 |
| -List, parse it to an array, and store it in the `/path/to/Aura.Uri/data` directory. |
158 |
| - |
159 |
| -[Public Suffix List]: http://publicsuffix.org/ |
160 |
| - |
161 |
| -* * * |
| 6 | +https://github.com/auraphp/Aura.Uri |
0 commit comments