nette/http 3.3.2

nette · Jan 12, 2025 · d64ea23 · d64ea23
1 parent e00f385
commit d64ea23
Show file tree

Hide file tree

Showing 16 changed files with 1,337 additions and 201 deletions.
diff --git a/http/bg/urls.texy b/http/bg/urls.texy
@@ -44,7 +44,18 @@ $url = new Url(
 );
 ```
 
-Следните методи са достъпни за извличане или промяна на отделни компоненти на URL:
+Класът `Url` имплементира интерфейса `JsonSerializable` и предоставя метода `__toString()`, което дава възможност за отпечатване на обекта или използването му с `json_encode()`.
+
+```php
+echo $url;
+echo json_encode([$url]);
+```
+
+
+URL Components .[method]
+------------------------
+
+Следните методи са достъпни за получаване или промяна на отделни компоненти на URL:
 
 .[language-php]
 | Setter | Getter | Върната стойност
@@ -72,7 +83,10 @@ $url = new Url(
 | `setQuery(string\|array $query)` | `getQueryParameters(): array`
 | `setQueryParameter(string $name, $val)`| `getQueryParameter(string $name)`
 
-Методът `getDomain(int $level = 2)` връща дясната или лявата страна на хоста. Ето как става това, ако хостът е `www.nette.org`:
+
+getDomain(int $level = 2): string .[method]
+-------------------------------------------
+Връща дясната или лявата част на хоста. Ето как работи, ако хостът е `www.nette.org`:
 
 .[language-php]
 | `getDomain(1)` | `'org'`
@@ -84,17 +98,33 @@ $url = new Url(
 | `getDomain(-3)` | `''`
 
 
-Класът `Url` имплементира интерфейса `JsonSerializable` и има метод `__toString()`, така че обектът може да бъде отпечатан или използван в данните, предадени на `json_encode()`.
+isEqual(string|Url $anotherUrl): bool .[method]
+-----------------------------------------------
+Проверява дали два URL адреса са идентични.
 
 ```php
-echo $url;
-echo json_encode([$url]);
+$url->isEqual('https://nette.org');
 ```
 
-Методът `isEqual(string|Url $anotherUrl): bool` проверява дали двата URL адреса са идентични.
+
+Url::isAbsolute(string $url): bool .[method]{data-version:3.3.2}
+----------------------------------------------------------------
+Проверява дали даден URL адрес е абсолютен. URL адресът се счита за абсолютен, ако започва със схема (напр. http, https, ftp), последвана от двоеточие.
 
 ```php
-$url->isEqual('https://nette.org');
+Url::isAbsolute('https://nette.org');    // true
+Url::isAbsolute('//nette.org');          // false
+```
+
+
+Url::removeDotSegments(string $path): string .[method]{data-version:3.3.2}
+--------------------------------------------------------------------------
+Нормализира URL пътя, като премахва специалните сегменти `.` и `..`. Този метод премахва излишните елементи на пътя по същия начин, по който го правят браузърите.
+
+```php
+Url::removeDotSegments('/path/../subtree/./file.txt');  // '/subtree/file.txt'
+Url::removeDotSegments('/../foo/./bar');                // '/foo/bar'
+Url::removeDotSegments('./today/../file.txt');          // 'file.txt'
 ```
 
 
@@ -118,7 +148,18 @@ $newUrl = $url
 echo $newUrl; // 'http://nette.org:8080/en/?name=param#footer'
 ```
 
-Следните методи са достъпни за извличане или промяна на отделни компоненти на URL:
+Класът `UrlImmutable` имплементира интерфейса `JsonSerializable` и предоставя метода `__toString()`, който ви позволява да отпечатате обекта или да го използвате с `json_encode()`.
+
+```php
+echo $url;
+echo json_encode([$url]);
+```
+
+
+URL Components .[method]
+------------------------
+
+Следните методи са достъпни за получаване или промяна на отделни компоненти на URL:
 
 .[language-php]
 | Wither | Getter | Върната стойност
@@ -136,6 +177,8 @@ echo $newUrl; // 'http://nette.org:8080/en/?name=param#footer'
 | | `getHostUrl(): string`| `'http://nette.org:8080'`
 | | `getAbsoluteUrl(): string` | пълен URL адрес
 
+Методът `withoutUserInfo()` премахва `user` и `password`.
+
 Можем да работим и с отделни параметри на заявката, като използваме:
 
 .[language-php]
@@ -144,16 +187,44 @@ echo $newUrl; // 'http://nette.org:8080/en/?name=param#footer'
 | `withQuery(string\|array $query)` | `getQueryParameters(): array`
 | `withQueryParameter(string $name, $val)` | `getQueryParameter(string $name)`
 
-Методът `getDomain(int $level = 2)` работи по същия начин като метода в `Url`. Методът `withoutUserInfo()` премахва `user` и `password`.
 
-Класът `UrlImmutable` имплементира интерфейса `JsonSerializable` и има метод `__toString()`, така че обектът може да бъде отпечатан или използван в данните, предадени на `json_encode()`.
+getDomain(int $level = 2): string .[method]
+-------------------------------------------
+Връща дясната или лявата част на хоста. Ето как работи, ако хостът е `www.nette.org`:
+
+.[language-php]
+| `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)` | `''`
+
+
+resolve(string $reference): UrlImmutable .[method]{data-version:3.3.2}
+----------------------------------------------------------------------
+Разрешава абсолютен URL адрес по същия начин, по който браузърът обработва връзките в HTML страница:
+- Ако връзката е абсолютен URL адрес (съдържа схема), той се използва непроменен.
+- Ако връзката започва с `//`, се прилага само схемата от текущия URL адрес.
+- Ако връзката започва с `/`, се създава абсолютен път от корена на домейна.
+- В останалите случаи URL адресът се конструира относително към текущия път.
 
 ```php
-echo $url;
-echo json_encode([$url]);
+$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` проверява дали двата URL адреса са идентични.
+
+isEqual(string|Url $anotherUrl): bool .[method]
+-----------------------------------------------
+Проверява дали два URL адреса са идентични.
+
+```php
+$url->isEqual('https://nette.org');
+```
 
 
 UrlScript .[#toc-urlscript]

diff --git a/http/cs/urls.texy b/http/cs/urls.texy
@@ -44,6 +44,17 @@ $url = new Url(
 );
 ```
 
+Třída `Url` implementuje rozhraní `JsonSerializable` a má metodu `__toString()`, takže objekt lze vypsat nebo použít v datech předávaných do `json_encode()`.
+
+```php
+echo $url;
+echo json_encode([$url]);
+```
+
+
+Komponenty URL .[method]
+------------------------
+
 Pro vrácení nebo změnu jednotlivých komponent URL jsou vám k dispozici tyto metody:
 
 .[language-php]
@@ -72,7 +83,10 @@ Můžeme pracovat i s jednotlivými query parametry pomocí:
 | `setQuery(string\|array $query)`  		| `getQueryParameters(): array`
 | `setQueryParameter(string $name, $val)`	| `getQueryParameter(string $name)`
 
-Metoda `getDomain(int $level = 2)` vrací pravou či levou část hostitele. Takto funguje, pokud host je `www.nette.org`:
+
+getDomain(int $level = 2): string .[method]
+-------------------------------------------
+Vrací pravou či levou část hostitele. Takto funguje, pokud host je `www.nette.org`:
 
 .[language-php]
 | `getDomain(1)`  |  `'org'`
@@ -84,17 +98,33 @@ Metoda `getDomain(int $level = 2)` vrací pravou či levou část hostitele. Tak
 | `getDomain(-3)` |  `''`
 
 
-Třída `Url` implementuje rozhraní `JsonSerializable` a má metodu `__toString()`, takže objekt lze vypsat nebo použít v datech předávaných do `json_encode()`.
+isEqual(string|Url $anotherUrl): bool .[method]
+-----------------------------------------------
+Ověří, zda jsou dvě URL shodné.
 
 ```php
-echo $url;
-echo json_encode([$url]);
+$url->isEqual('https://nette.org');
 ```
 
-Metoda `isEqual(string|Url $anotherUrl): bool` ověří, zda jsou dvě URL shodné.
+
+Url::isAbsolute(string $url): bool .[method]{data-version:3.3.2}
+----------------------------------------------------------------
+Ověřuje, zda je URL absolutní. URL je považována za absolutní, pokud začíná schématem (např. http, https, ftp) následovaným dvojtečkou.
 
 ```php
-$url->isEqual('https://nette.org');
+Url::isAbsolute('https://nette.org');    // true
+Url::isAbsolute('//nette.org');          // false
+```
+
+
+Url::removeDotSegments(string $path): string .[method]{data-version:3.3.2}
+--------------------------------------------------------------------------
+Normalizuje cestu v URL odstraněním speciálních segmentů `.` a `..`. Metoda odstraňuje nadbytečné prvky cesty stejným způsobem, jako to dělají webové prohlížeče.
+
+```php
+Url::removeDotSegments('/path/../subtree/./file.txt');  // '/subtree/file.txt'
+Url::removeDotSegments('/../foo/./bar');                // '/foo/bar'
+Url::removeDotSegments('./today/../file.txt');          // 'file.txt'
 ```
 
 
@@ -118,6 +148,17 @@ $newUrl = $url
 echo $newUrl; // 'http://nette.org:8080/cs/?name=param#footer'
 ```
 
+Třída `UrlImmutable` implementuje rozhraní `JsonSerializable` a má metodu `__toString()`, takže objekt lze vypsat nebo použít v datech předávaných do `json_encode()`.
+
+```php
+echo $url;
+echo json_encode([$url]);
+```
+
+
+Komponenty URL .[method]
+------------------------
+
 Pro vrácení nebo změnu jednotlivých komponent URL slouží metody:
 
 .[language-php]
@@ -136,6 +177,8 @@ Pro vrácení nebo změnu jednotlivých komponent URL slouží metody:
 | 											| `getHostUrl(): string`		| `'http://nette.org:8080'`
 | 											| `getAbsoluteUrl(): string` 	| celá URL
 
+Metoda `withoutUserInfo()` odstraňuje `user` a `password`.
+
 Můžeme pracovat i s jednotlivými query parametry pomocí:
 
 .[language-php]
@@ -144,16 +187,44 @@ Můžeme pracovat i s jednotlivými query parametry pomocí:
 | `withQuery(string\|array $query)` 	    | `getQueryParameters(): array`
 | `withQueryParameter(string $name, $val)`  | `getQueryParameter(string $name)`
 
-Metoda `getDomain(int $level = 2)` funguje stejně, jako její jmenovkyně ze třídy `Url`. Metoda `withoutUserInfo()` odstraňuje `user` a `password`.
 
-Třída `UrlImmutable` implementuje rozhraní `JsonSerializable` a má metodu `__toString()`, takže objekt lze vypsat nebo použít v datech předávaných do `json_encode()`.
+getDomain(int $level = 2): string .[method]
+-------------------------------------------
+Vrací pravou či levou část hostitele. Takto funguje, pokud host je `www.nette.org`:
+
+.[language-php]
+| `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)` |  `''`
+
+
+resolve(string $reference): UrlImmutable .[method]{data-version:3.3.2}
+----------------------------------------------------------------------
+Odvozuje absolutní URL stejným způsobem, jakým prohlížeč zpracovává odkazy na HTML stránce:
+- pokud je odkaz absolutní URL (obsahuje schéma), použije se beze změny
+- pokud odkaz začíná `//`, převezme se pouze schéma z aktuální URL
+- pokud odkaz začíná `/`, vytvoří se absolutní cesta od kořene domény
+- v ostatních případech se URL sestaví relativně vůči aktuální cestě
 
 ```php
-echo $url;
-echo json_encode([$url]);
+$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'
 ```
 
-Metoda `isEqual(string|Url $anotherUrl): bool` ověří, zda jsou dvě URL shodné.
+
+isEqual(string|Url $anotherUrl): bool .[method]
+-----------------------------------------------
+Ověří, zda jsou dvě URL shodné.
+
+```php
+$url->isEqual('https://nette.org');
+```
 
 
 UrlScript