https://github.com/xp-forge/uri
URI handling
https://github.com/xp-forge/uri
fluent-interface php rfc-3986 uri
Last synced: 5 months ago
JSON representation
URI handling
- Host: GitHub
- URL: https://github.com/xp-forge/uri
- Owner: xp-forge
- Created: 2017-03-24T17:19:41.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2025-01-19T10:21:54.000Z (about 1 year ago)
- Last Synced: 2025-03-24T12:39:41.435Z (11 months ago)
- Topics: fluent-interface, php, rfc-3986, uri
- Language: PHP
- Size: 143 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: ChangeLog.md
Awesome Lists containing this project
README
URI handling
============
[](https://github.com/xp-forge/uri/actions)
[](https://github.com/xp-framework/core)
[](https://github.com/xp-framework/core/blob/master/LICENCE.md)
[](http://php.net/)
[](http://php.net/)
[](https://packagist.org/packages/xp-forge/uri)
A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource.
```
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
## Examples
### Parsing from a string
The most common case will include constructing URIs from a given input string.
```php
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.
```php
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:
```php
use util\URI;
$uri= new URI('http://localhost/home/');
$uri->resolve('/index.html'); // util.URI
$uri->resolve('index.html'); // util.URI
$uri->resolve('?sort=name'); // util.URI
$uri->resolve('#top'); // util.URI
$uri->resolve('//example.com'); // util.URI
$uri->resolve('https://localhost'); // util.URI
```
### 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.
```php
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")
```