Skip to content
Tutorials Center
My learning

Topics

PHP Reference ยท Standard PHP Library and Classes

The Uri\Rfc3986\Uri class

Reference for PHP 8.5 Uri\Rfc3986\Uri: parse and build RFC 3986 URIs as immutable objects, read parts, change them with with*() methods and resolve relative references.

PHP 8.5 has an always-available uri extension with two immutable classes for working with web addresses. Uri\Rfc3986\Uri follows the generic URI syntax of RFC 3986, which is the right choice for general URIs such as mailto:, urn: or API endpoints. Its sibling Uri\WhatWg\Url follows the WHATWG URL standard, which is what browsers do.

Before this, the only built-in tool was parse_url(), which returns a plain array, accepts nearly anything and does no normalization. The class gives you validation, typed getters, safe modification and relative-reference resolution.

PHP
use Uri\Rfc3986\Uri;

$uri = new Uri("https://example.com:8080/docs?page=2#top");
echo $uri->getHost();   // example.com

Try it

PHP Reading the parts of a URI

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

PHP Changing, resolving and comparing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Syntax

PHP
// abridged
final class Uri\Rfc3986\Uri
{
    public function __construct(string $uri, ?Uri\Rfc3986\Uri $baseUrl = null);
    public static function parse(string $uri, ?Uri\Rfc3986\Uri $baseUrl = null): ?static;
    public function getScheme(): ?string;
    public function getUserInfo(): ?string;
    public function getHost(): ?string;
    public function getPort(): ?int;
    public function getPath(): string;
    public function getQuery(): ?string;
    public function getFragment(): ?string;
    public function withHost(?string $host): static;   // and withScheme, withPort, withPath, withQuery ...
    public function resolve(string $uri): static;
    public function equals(Uri\Rfc3986\Uri $uri, Uri\UriComparisonMode $mode = Uri\UriComparisonMode::ExcludeFragment): bool;
    public function toString(): string;
    public function toRawString(): string;
}
Name Description
$uri The URI string to parse.
$baseUrl Optional absolute base against which $uri is resolved while parsing.
get*() Return a component in decoded, normalized form; the getRaw*() variants return it exactly as written. Missing parts are null.
with*() Return a new object with one component changed. Passing null removes the component where that makes sense.
resolve($uri) Resolves a relative reference against this URI (RFC 3986 section 5).
equals($uri, $mode) Compares two URIs after normalization.
toString() / toRawString() The normalized or the original text.

Return value: the constructor creates the object; parse() returns null instead of throwing when the string is invalid.

Errors / Exceptions: new Uri() and with*() with invalid input throw Uri\InvalidUriException. resolve() throws it when the URI is not absolute enough to serve as a base.

Usage notes

  • The class is immutable. with*() never changes the original, as the second example shows; keep the returned object.
  • parse() for untrusted input. It gives null on failure, which fits ?? and early returns better than a try/catch.
  • Raw versus normalized. Host names are lowercased and dot segments removed in the normal getters (compare getHost() with getRawHost() and getPath() with getRawPath()), while the raw getters keep the input.
  • Not a validator for "this is a safe link". A well-formed URI can still point anywhere. Check the scheme (https) and host against an allow-list before redirecting or fetching.
  • Relative URIs are valid (/path?x=1), but resolve() needs an absolute base.
  • parse_url() remains for quick, lenient splitting; use the class when correctness matters.
  • Added in PHP 8.5. Both URI classes live in Uri\, and the comparison enum is Uri\UriComparisonMode.