aura / uri
The Aura Uri package provides objects to build and manipulate URL strings.
Installs: 63 863
Dependents: 1
Suggesters: 0
Security: 0
Stars: 24
Watchers: 10
Forks: 12
Open Issues: 0
Requires
- php: ^5.4 || ^7.0 || ^8.0
Requires (Dev)
- phpunit/phpunit: ^5.7 || ^4.8 || ^9.5
- yoast/phpunit-polyfills: ^1.1
README
The Auri.Uri
package provides objects to help you create and manipulate URLs,
including query strings and path elements. It does so by splitting up the pieces
of the URL and allowing you modify them individually; you can then fetch
them as a single URL string. This helps when building complex links,
such as in a paged navigation system.
This package is compliant with PSR-0, PSR-1, and PSR-2. If you notice compliance oversights, please send a patch via pull request.
Getting Started
Instantiation
The easiest way to get started is to use the UrlFactory to create a Url object.
<?php use Aura\Uri\Url\Factory as UrlFactory; use Aura\Uri\PublicSuffixList; $psl = new PublicSuffixList(require '/path/to/Aura.Uri/data/public-suffix-list.php'); $url_factory = new UrlFactory($_SERVER, $psl); $url = $url_factory->newCurrent();
You can populate the URL properties from a URL string:
<?php $string = 'http://anonymous:guest@example.com/path/to/index.php/foo/bar.xml?baz=dib#anchor'); $url = $url_factory->newInstance($string); // now the $url properties are ... // // $url->scheme => 'http' // $url->user => 'anonymous' // $url->pass => 'guest' // $url->host => Aura\Uri\Host, with these methods: // ->get() => 'example.com' // ->getSubdomain() => null // ->getRegisterableDomain() => 'example.com' // ->getPublicSuffix() => 'com' // $url->port => null // $url->path => Aura\Uri\Path, with these ArrayObject elements: // ['path', 'to', 'index.php', 'foo', 'bar'] // and this method: // ->getFormat() => '.xml' // $url->query => Aura\Uri\Query, with these ArrayObject elements: // ['baz' => 'dib'] // $url->fragment => 'anchor'
Alternatively, you can use the factory to create a URL representing the current web request URI:
<?php $url = $url_factory->newCurrent();
Manipulation
After we have created the URL object, we can modify the component parts, then fetch a new URL string from the modified object.
<?php // start with a full URL $string = 'http://anonymous:guest@example.com/path/to/index.php/foo/bar.xml?baz=dib#anchor'; $url = $url_factory->newInstance($string); // change to 'https://' $url->setScheme('https'); // remove the username and password $url->setUser(null); $url->setPass(null); // change the value of 'baz' from 'dib' to 'zab' $url->query->baz = 'zab'; // add a new query element called 'zim' with a value of 'gir' $url->query->zim = 'gir'; // reset the path to something else entirely. // this will additionally set the format to '.php'. $url->path->setFromString('/something/else/entirely.php'); // add another path element $url->path[] = 'another'; // get the url as a string; this will be without the scheme, host, port, // user, or pass. $new_url = $url->get(); // the $new_url string is as follows; notice how the format // is always applied to the last path-element: // /something/else/entirely/another.php?baz=zab&zim=gir#anchor // get the full url string, including scheme, host, port, user, and pass. $full_url = $url->getFull(); // the $full_url string is as follows: // https://example.com/something/else/entirely/another.php?baz=zab&zim=gir#anchor
Public Suffix List Host Parsing
Host Component Parts
In addition to URL creation and manipulation, Aura.Uri
is capable of parsing a
host into its component parts, namely the host's subdomain, registerable domain,
and public suffix. A host's component parts are available via properties on the
Aura.Uri host object, as seen in the examples above.
Public Suffix List
This parsing capability is possible as a result of the Public Suffix List, a community resource and initiative of Mozilla.
Updating the Public Suffix List
As the Public Suffix List is both an external resource and a living document, it's
important that you update your copy of the list from time to time. You can do this
by executing the provided update.php
script.
php /path/to/Aura.Uri/scripts/update.php
Executing update.php
will retrieve the most current version of the Public Suffix
List, parse it to an array, and store it in the /path/to/Aura.Uri/data
directory.