URL-Parser und -Ersteller

Die Klassen Url, UrlImmutable und UrlScript erleichtern das Verwalten, Parsen und Manipulieren von URLs.

Installation und Anforderungen

Url

Die Klasse Nette\Http\Url erleichtert die Arbeit mit der URL und ihren einzelnen Komponenten, die in diesem Diagramm skizziert werden:

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

Die URL-Generierung ist intuitiv:

use Nette\Http\Url;

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

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

Sie können die URL auch parsen und dann manipulieren:

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

Die folgenden Methoden stehen zur Verfügung, um einzelne URL-Komponenten zu erhalten oder zu ändern:

Setter Getter Rückgabewert
setScheme(string $scheme) getScheme(): string 'http'
setUser(string $user) getUser(): string 'john'
setPassword(string $password) getPassword(): string 'xyz*12'
setHost(string $host) getHost(): string 'nette.org'
setPort(int $port) getPort(): ?int 8080
  getDefaultPort(): ?int 80
setPath(string $path) getPath(): string '/en/download'
setQuery(string|array $query) getQuery(): string 'name=param'
setFragment(string $fragment) getFragment(): string 'footer'
  getAuthority(): string 'nette.org:8080'
  getHostUrl(): string 'http://nette.org:8080'
  getAbsoluteUrl(): string vollständige URL

Warnung: Bei der Arbeit mit einer URL, die aus einer HTTP-Anfrage stammt, ist zu beachten, dass sie das Fragment nicht enthält, da der Browser es nicht an den Server sendet.

Wir können auch mit einzelnen Abfrageparametern arbeiten:

Setter Getter
setQuery(string|array $query) getQueryParameters(): array
setQueryParameter(string $name, $val) getQueryParameter(string $name)

Die Methode getDomain(int $level = 2) gibt den rechten oder linken Teil des Hosts zurück. So funktioniert es, wenn der Host www.nette.org ist:

getDomain(1) 'org'
getDomain(2) 'nette.org'
getDomain(3) 'www.nette.org'
getDomain(0) 'www.nette.org'
getDomain(-1) 'www.nette'
getDomain(-2) 'www'
getDomain(-3) ''

Die Klasse Url implementiert die Schnittstelle JsonSerializable und verfügt über eine Methode __toString(), damit das Objekt gedruckt oder in Daten verwendet werden kann, die an json_encode() übergeben werden.

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

Die Methode isEqual(string|Url $anotherUrl): bool prüft, ob die beiden URLs identisch sind.

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

UrlImmutable

Die Klasse Nette\Http\UrlImmutable ist eine unveränderbare Alternative zur Klasse Url (so wie in PHP DateTimeImmutable eine unveränderbare Alternative zu DateTime ist). Anstelle von Settern hat sie sogenannte Wither, die das Objekt nicht verändern, sondern neue Instanzen mit einem geänderten Wert zurückgeben:

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://nette.org:8080/en/?name=param#footer'

Die folgenden Methoden stehen zur Verfügung, um einzelne URL-Komponenten zu erhalten oder zu ändern:

Wither Getter Rückgabewert
withScheme(string $scheme) getScheme(): string 'http'
withUser(string $user) getUser(): string 'john'
withPassword(string $password) getPassword(): string 'xyz*12'
withHost(string $host) getHost(): string 'nette.org'
withPort(int $port) getPort(): ?int 8080
  getDefaultPort(): ?int 80
withPath(string $path) getPath(): string '/en/download'
withQuery(string|array $query) getQuery(): string 'name=param'
withFragment(string $fragment) getFragment(): string 'footer'
  getAuthority(): string 'nette.org:8080'
  getHostUrl(): string 'http://nette.org:8080'
  getAbsoluteUrl(): string vollständige URL

Wir können auch mit einzelnen Abfrageparametern arbeiten:

Wither Getter
withQuery(string|array $query) getQueryParameters(): array
withQueryParameter(string $name, $val) getQueryParameter(string $name)

Die Methode getDomain(int $level = 2) funktioniert genauso wie die Methode in Url. Mit der Methode withoutUserInfo() werden user und password entfernt.

Die Klasse UrlImmutable implementiert die Schnittstelle JsonSerializable und verfügt über eine Methode __toString(), damit das Objekt gedruckt oder in Daten verwendet werden kann, die an json_encode() übergeben werden.

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

Die Methode isEqual(string|Url $anotherUrl): bool prüft, ob die beiden URLs identisch sind.

UrlScript

Die Klasse Nette\Http\UrlScript ist ein Abkömmling von UrlImmutable und unterscheidet zusätzlich diese logischen Teile der URL:

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

Die folgenden Methoden sind verfügbar, um diese Teile zu erhalten:

Getter Rückgabewert
getScriptPath(): string '/admin/script.php'
getBasePath(): string '/admin/'
getBaseUrl(): string 'http://nette.org/admin/'
getRelativePath(): string 'script.php'
getRelativeUrl(): string 'script.php/pathinfo/?name=param#footer'
getPathInfo(): string '/pathinfo/'

Wir erstellen die Objekte UrlScript nicht direkt, aber die Methode Nette\Http\Request::getUrl() gibt sie zurück.

Version: 4.0