Working with URLs

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

→ Installation and requirements

Url

The Nette\Http\Url class allows easy manipulation of URLs and their individual components, as depicted 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

Generating URLs 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 a 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 has a __toString() method, so the object can be printed or used in data passed to json_encode().

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

URL Components

The following methods are available to retrieve or modify 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 work 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 in the same way web 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('/en/');

echo $newUrl; // 'http://john:xyz%2A12@nette.org:8080/en/?name=param#footer'

The UrlImmutable class implements the JsonSerializable interface and has a __toString() method, so the object can be printed or used in data passed to json_encode().

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

URL Components

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

The withoutUserInfo() method removes user and password.

We can also work 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 adopted
• 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 project's root directory, 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 the domain and the path part to the application's root directory
• basePath is the path part to the application's root directory
• 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 the query string and fragment
• pathInfo is a now rarely used part of the URL after the script name

The following methods are available to retrieve these parts of the URL:

We usually do not create UrlScript objects directly; instead, the Nette\Http\Request::getUrl() method returns it with the components already correctly set for the current HTTP request.