xp-forge/uri

URIs

URI handling

, _(*1)

A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource., _(*2)

  foo://example.com:8042/over/there?name=ferret#nose
  \_/   \______________/\_________/ \_________/ \__/
   |           |            |            |        |
scheme     authority       path        query   fragment
   |   _____________________|__
  / \ /                        \
  urn:example:animal:ferret:nose

See https://tools.ietf.org/html/rfc3986, _(*3)

Examples

Parsing from a string

The most common case will include constructing URIs from a given input string., _(*4)

use util\URI;

$uri= new URI('https://user:password@localhost:8443/index?sort=name#top');
$uri->isOpaque();     // false - it's a hierarchical URI
$uri->scheme();       // "https"
$uri->authority();    // util.Authority("localhost", 8443, "user", util.Secret("password"))
$uri->host();         // "localhost"
$uri->port();         // 8443
$uri->user();         // "user"
$uri->password();     // util.Secret("password")
$uri->path();         // "index"
$uri->query();        // "sort=name"
$uri->params();       // util.uri.Parameters("sort=name")
$uri->param('sort');  // "name"
$uri->fragment();     // "top"
$uri->resource();     // "/index?sort=name#top"

Creating or modifying

URI instances are immutable. However, a fluent interface is offered via with() and using(). Both return fresh instances., _(*5)

use util\URI;

$uri= URI::with()->scheme('mailto')->path('timm@example.com')->param('Subject', 'Hello')->create();
$uri->isOpaque();   // true - it's an opaque URI
$uri->scheme();     // "mailto"
$uri->authority();  // null
(string)$uri;       // "mailto:timm@example.com?Subject=Hello"

$copy= $uri->using()->path('cc@example.com')->create();
(string)$copy;      // "mailto:cc@example.com?Subject=Hello"

Resolving URIs

Given http://localhost/home/ as the base URI, you can resolve links in its context using the resolve() method:, _(*6)

use util\URI;

$uri= new URI('http://localhost/home/');
$uri->resolve('/index.html');       // util.URI<http://localhost/index.html>
$uri->resolve('index.html');        // util.URI<http://localhost/home/index.html>
$uri->resolve('?sort=name');        // util.URI<http://localhost/home/?sort=name>
$uri->resolve('#top');              // util.URI<http://localhost/home/#top>
$uri->resolve('//example.com');     // util.URI<http://example.com>
$uri->resolve('https://localhost'); // util.URI<https://localhost>

Filesystem

URIs can point to filesystem paths. Converting between the two is not trivial - you need to handle Windows UNC paths correctly. The URI class' file() and asPath() methods take care of this., _(*7)

use util\URI;

$uri= URI::file('/etc/php.ini');
(string)$uri;       // "file:///etc/php.ini"

$uri= new URI('file://c:/Windows');
$uri->path();       // "C:/Windows"
$uri->asPath();     // io.Path("C:\Windows")

$uri= new URI('file://share/file.txt');
$uri->authority();  // util.Authority("share")
$uri->path();       // "/file.txt"
$uri->asPath();     // io.Path("\\share\file.txt")