scratch – Blame information for rev 126
?pathlinks?
Rev | Author | Line No. | Line |
---|---|---|---|
126 | office | 1 | Aura.Uri |
2 | ======== |
||
3 | |||
4 | [![Build Status](https://travis-ci.org/auraphp/Aura.Uri.png?branch=develop)](https://travis-ci.org/auraphp/Aura.Uri) |
||
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 | use Aura\Uri\PublicSuffixList; |
||
41 | |||
42 | $psl = new PublicSuffixList(require '/path/to/Aura.Uri/data/public-suffix-list.php'); |
||
43 | $url_factory = new UrlFactory($_SERVER, $psl); |
||
44 | $url = $url_factory->newCurrent(); |
||
45 | ``` |
||
46 | |||
47 | When using the factory, you can populate the URL properties from a URL |
||
48 | string: |
||
49 | |||
50 | ```php |
||
51 | <?php |
||
52 | $string = 'http://anonymous:guest@example.com/path/to/index.php/foo/bar.xml?baz=dib#anchor'); |
||
53 | $url = $url_factory->newInstance($string); |
||
54 | |||
55 | // now the $url properties are ... |
||
56 | // |
||
57 | // $url->scheme => 'http' |
||
58 | // $url->user => 'anonymous' |
||
59 | // $url->pass => 'guest' |
||
60 | // $url->host => Aura\Uri\Host, with these methods: |
||
61 | // ->get() => 'example.com' |
||
62 | // ->getSubdomain() => null |
||
63 | // ->getRegisterableDomain() => 'example.com' |
||
64 | // ->getPublicSuffix() => 'com' |
||
65 | // $url->port => null |
||
66 | // $url->path => Aura\Uri\Path, with these ArrayObject elements: |
||
67 | // ['path', 'to', 'index.php', 'foo', 'bar'] |
||
68 | // and this method: |
||
69 | // ->getFormat() => '.xml' |
||
70 | // $url->query => Aura\Uri\Query, with these ArrayObject elements: |
||
71 | // ['baz' => 'dib'] |
||
72 | // $url->fragment => 'anchor' |
||
73 | ``` |
||
74 | |||
75 | Alternatively, you can use the factory to create a URL representing the |
||
76 | current web request URI: |
||
77 | |||
78 | ```php |
||
79 | <?php |
||
80 | $url = $url_factory->newCurrent(); |
||
81 | ``` |
||
82 | |||
83 | |||
84 | Manipulation |
||
85 | ------------ |
||
86 | |||
87 | After we have created the URL object, we can modify the component parts, then |
||
88 | fetch a new URL string from the modified object. |
||
89 | |||
90 | ```php |
||
91 | <?php |
||
92 | // start with a full URL |
||
93 | $string = 'http://anonymous:guest@example.com/path/to/index.php/foo/bar.xml?baz=dib#anchor'; |
||
94 | $url = $url_factory->newInstance($string); |
||
95 | |||
96 | // change to 'https://' |
||
97 | $url->setScheme('https'); |
||
98 | |||
99 | // remove the username and password |
||
100 | $url->setUser(null); |
||
101 | $url->setPass(null); |
||
102 | |||
103 | // change the value of 'baz' from 'dib' to 'zab' |
||
104 | $url->query->baz = 'zab'; |
||
105 | |||
106 | // add a new query element called 'zim' with a value of 'gir' |
||
107 | $url->query->zim = 'gir'; |
||
108 | |||
109 | // reset the path to something else entirely. |
||
110 | // this will additionally set the format to '.php'. |
||
111 | $url->path->setFromString('/something/else/entirely.php'); |
||
112 | |||
113 | // add another path element |
||
114 | $url->path[] = 'another'; |
||
115 | |||
116 | // get the url as a string; this will be without the scheme, host, port, |
||
117 | // user, or pass. |
||
118 | $new_url = $url->get(); |
||
119 | |||
120 | // the $new_url string is as follows; notice how the format |
||
121 | // is always applied to the last path-element: |
||
122 | // /something/else/entirely/another.php?baz=zab&zim=gir#anchor |
||
123 | |||
124 | // get the full url string, including scheme, host, port, user, and pass. |
||
125 | $full_url = $url->getFull(); |
||
126 | |||
127 | // the $full_url string is as follows: |
||
128 | // https://example.com/something/else/entirely/another.php?baz=zab&zim=gir#anchor |
||
129 | ``` |
||
130 | |||
131 | Public Suffix List Host Parsing |
||
132 | =============================== |
||
133 | |||
134 | Host Component Parts |
||
135 | -------------------- |
||
136 | |||
137 | In addition to URL creation and manipulation, `Aura.Uri` is capable of parsing a |
||
138 | host into its component parts, namely the host's subdomain, registerable domain, |
||
139 | and public suffix. A host's component parts are available via properties on the |
||
140 | Aura.Uri host object, as seen in the examples above. |
||
141 | |||
142 | Public Suffix List |
||
143 | ------------------ |
||
144 | |||
145 | This parsing capability is possible as a result of the [Public Suffix List][], a community |
||
146 | resource and initiative of Mozilla. |
||
147 | |||
148 | Updating the Public Suffix List |
||
149 | ------------------------------- |
||
150 | |||
151 | As the Public Suffix List is both an external resource and a living document, it's |
||
152 | important that you update your copy of the list from time to time. You can do this |
||
153 | by executing the provided `update.php` script. |
||
154 | |||
155 | `php /path/to/Aura.Uri/scripts/update.php` |
||
156 | |||
157 | Executing `update.php` will retrieve the most current version of the Public Suffix |
||
158 | List, parse it to an array, and store it in the `/path/to/Aura.Uri/data` directory. |
||
159 | |||
160 | [Public Suffix List]: http://publicsuffix.org/ |
||
161 | |||
162 | * * * |