scratch – Blame information for rev 126

Subversion Repositories:
Rev:
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 * * *