URL Utility

The Url, UrlImmutable, and UrlScript classes make it easy to manage, parse, and manipulate URLs.

→ Installation and requirements

Url

The Nette\Http\Url class makes it easy to work with the URL and its individual components, which are outlined in this diagram:

scheme  user  password  host   port    path        query  fragment
  |      |      |        |      |       |            |       |
/--\   /--\ /------\ /-------\ /--\/----------\ /--------\ /----\
http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer
\______\__________________________/
    |               |
 hostUrl        authority

URL generation is intuitive:

use Nette\Http\Url;

$url = new Url;
$url->setScheme('https')
	->setHost('localhost')
	->setPath('/edit')
	->setQueryParameter('foo', 'bar');

echo $url; // 'https://localhost/edit?foo=bar'

You can also parse the URL and then manipulate it:

$url = new Url(
	'http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer',
);

The Url class implements the JsonSerializable interface and provides the __toString() method, making it possible to print the object or use it with json_encode().

echo $url;
echo json_encode([$url]);

URL Components

The following methods are available to get or change individual URL components:

Warning: When working with a URL obtained from an HTTP request, keep in mind that it will not contain the fragment, as the browser does not send it to the server.

We can also operate with individual query parameters using:

getDomain (int $level = 2): string

Returns the right or left part of the host. Here's how it works if the host is www.nette.org:

isEqual (string|Url $anotherUrl): bool

Checks if two URLs are identical.

$url->isEqual('https://nette.org');

Url::isAbsolute (string $url): bool

Checks if a URL is absolute. A URL is considered absolute if it begins with a scheme (e.g., http, https, ftp) followed by a colon.

Url::isAbsolute('https://nette.org');    // true
Url::isAbsolute('//nette.org');          // false

Url::removeDotSegments (string $path): string

Normalizes a URL path by removing special segments . and ... This method removes redundant path elements the same way browsers do.

Url::removeDotSegments('/path/../subtree/./file.txt');  // '/subtree/file.txt'
Url::removeDotSegments('/../foo/./bar');                // '/foo/bar'
Url::removeDotSegments('./today/../file.txt');          // 'file.txt'

UrlImmutable

The Nette\Http\UrlImmutable class is an immutable alternative to the Url class (similar to how DateTimeImmutable is an immutable alternative to DateTime in PHP). Instead of setters, it has withers, which do not change the object but return new instances with the modified value:

use Nette\Http\UrlImmutable;

$url = new UrlImmutable(
	'http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer',
);

$newUrl = $url
	->withUser('')
	->withPassword('')
	->withPath('/cs/');

echo $newUrl; // 'http://nette.org:8080/cs/?name=param#footer'

The UrlImmutable class implements the JsonSerializable interface and provides the __toString() method, allowing you to print the object or use it with json_encode().

echo $url;
echo json_encode([$url]);

URL Components

The following methods are available to get or change individual URL components:

The withoutUserInfo() method removes user and password.

We can also operate with individual query parameters using:

getDomain (int $level = 2): string

Returns the right or left part of the host. Here's how it works if the host is www.nette.org:

resolve (string $reference): UrlImmutable

Resolves an absolute URL in the same way a browser processes links on an HTML page:

• If the link is an absolute URL (contains a scheme), it is used unchanged.
• If the link begins with //, only the scheme from the current URL is applied.
• If the link begins with /, an absolute path from the domain root is created.
• In other cases, the URL is constructed relative to the current path.

$url = new UrlImmutable('https://example.com/path/page');
echo $url->resolve('../foo');           // 'https://example.com/foo'
echo $url->resolve('/bar');             // 'https://example.com/bar'
echo $url->resolve('sub/page.html');    // 'https://example.com/path/sub/page.html'

isEqual (string|Url $anotherUrl): bool

Checks if two URLs are identical.

$url->isEqual('https://nette.org');

UrlScript

The Nette\Http\UrlScript class is a descendant of UrlImmutable and extends it with additional virtual URL components, such as the root directory of the project, etc. Like its parent class, it is an immutable object.

The following diagram shows the components that UrlScript recognizes:

     baseUrl    basePath  relativePath  relativeUrl
        |          |        |               |
/---------------/-----\/--------\---------------------------\
http://nette.org/admin/script.php/pathinfo/?name=param#footer
                \_______________/\________/
                       |              |
                  scriptPath       pathInfo

• baseUrl is the base URL of the application including domain and part of the path to the root directory of the application
• basePath is part of the path to the root directory of the application
• scriptPath is the path to the current script
• relativePath is the script name (and possibly additional path segments) relative to basePath
• relativeUrl is the entire part of the URL after baseUrl, including query string and fragment.
• pathInfo is a now rarely used part of the URL after the script name

The following methods are available to get these parts:

We do not create objects UrlScript directly, but the method Nette\Http\Request::getUrl() returns it.