wip

Author: dg

http/cs/request.texy

@@ -4,9 +4,9 @@ HTTP request
 .[perex]
 Nette zapouzdřuje HTTP požadavek do objektů se srozumitelným API a zároveň poskytuje sanitizační filtr.
 
-HTTP požadavek představuje objekt [api:Nette\Http\Request], ke kterému se dostanete tak, že si jej necháte předat pomocí [dependency injection |dependency-injection:passing-dependencies]. V presenterech stačí jen zavolat `$httpRequest = $this->getHttpRequest()`.
+HTTP požadavek představuje objekt [api:Nette\Http\Request]. Pokud pracujete s Nette, tento objekt je automaticky vytvořen frameworkem a můžete si jej nechat předat pomocí [dependency injection |dependency-injection:passing-dependencies]. V presenterech stačí jen zavolat metodu `$this->getHttpRequest()`. Pokud pracujete mimo Nette Framework, můžete si vytvořit objekt pomocí [RequestFactory|#RequestFactory].
 
-Co je důležité, tak že Nette když [vytváří|#RequestFactory] tento objekt, všechny vstupní parametry GET, POST, COOKIE a také URL pročistí od kontrolních znaků a neplatných UTF-8 sekvencí. Takže s daty pak můžete bezpečně dále pracovat. Očištěná data se následně používají v presenterech a formulářích.
+Velkou předností Nette je, že při vytváření objektu automaticky pročišťuje všechny vstupní parametry GET, POST, COOKIE a také URL od kontrolních znaků a neplatných UTF-8 sekvencí. S těmito daty pak můžete bezpečně dále pracovat. Očištěná data se následně používají v presenterech a formulářích.
 
 → [Instalace a požadavky |@home#Instalace]
 
@@ -199,28 +199,35 @@ echo $httpRequest->detectLanguage($langs); // en
 RequestFactory
 ==============
 
-Objekt aktuálního HTTP requestu vyrobí [api:Nette\Http\RequestFactory]. Pokud píšete aplikaci, která nepoužívá DI kontejner, vyrobíte request takto:
+Třída [api:Nette\Http\RequestFactory] slouží k vytvoření instance `Nette\Http\Request`, která reprezentuje aktuální HTTP požadavek. (Pokud pracujete s Nette, objekt HTTP požadavku je automaticky vytvořen frameworkem.)
 
 ```php
 $factory = new Nette\Http\RequestFactory;
 $httpRequest = $factory->fromGlobals();
 ```
 
-RequestFactory lze před zavoláním `fromGlobals()` konfigurovat. Můžeme vypnout sanitizaci vstupních parametrů od kontrolních znaků a neplatných UTF-8 sekvencí pomocí `$factory->setBinary()`. A také nastavit proxy server pomocí `$factory->setProxy(...)`, což je důležité pro správnou detekci IP adresy uživatele.
+Metoda `fromGlobals()` vytvoří objekt požadavku na základě aktuálních globálních proměnných PHP (`$_GET`, `$_POST`, `$_COOKIE`, `$_FILES` a `$_SERVER`). Při vytváření objektu automaticky pročišťuje všechny vstupní parametry GET, POST, COOKIE a také URL od kontrolních znaků a neplatných UTF-8 sekvencí, což zajišťuje bezpečnost při další práci s těmito daty.
 
-Pomocí tzv. filtrů lze URL vyčistit od znaků, které se do něj mohou dostat např. kvůli špatně implementovaným komentářovým systémům na různých cizích webech:
+RequestFactory lze před zavoláním `fromGlobals()` konfigurovat:
+
+- metodou `$factory->setBinary()` vypnete automatické čištění vstupních parametrů od kontrolních znaků a neplatných UTF-8 sekvencí.
+- metodou `$factory->setProxy(...)` uvedete IP adresu [proxy serveru |configuration#HTTP proxy], což je nezbytné pro správnou detekci IP adresy uživatele.
+
+RequestFactory umožňuje definovat filtry, které automaticky transformují části URL požadavku. Tyto filtry odstraňují nežádoucí znaky z URL, které tam mohou být vloženy například nesprávnou implementací komentářových systémů na různých webech:
 
 ```php
-// odstraníme mezery z cesty
+// odstranění mezer z cesty
 $requestFactory->urlFilters['path']['%20'] = '';
 
-// odstraníme tečku, čárku nebo pravou závorku z konce URI
+// odstranění tečky, čárky nebo pravé závorky z konce URI
 $requestFactory->urlFilters['url']['[.,)]$'] = '';
 
-// vyčistíme cestu od zdvojených lomítek (výchozí filtr)
+// vyčištění cesty od zdvojených lomítek (výchozí filtr)
 $requestFactory->urlFilters['path']['/{2,}'] = '/';
 ```
 
+První klíč `'path'` nebo `'url'` určuje, na kterou část URL se filtr použije. Druhý klíč je regulární výraz, který se má vyhledat, a hodnota je náhrada, která se použije místo nalezeného textu.
+
 
 Uploadované soubory
 ===================

http/cs/response.texy

@@ -4,7 +4,7 @@ HTTP response
 .[perex]
 Nette zapouzdřuje HTTP odpověď do objektů se srozumitelným API.
 
-HTTP odpověď představuje objekt [api:Nette\Http\Response], ke kterému se dostanete tak, že si jej necháte předat pomocí [dependency injection |dependency-injection:passing-dependencies]. V presenterech stačí jen zavolat `$httpResponse = $this->getHttpResponse()`.
+HTTP odpověď představuje objekt [api:Nette\Http\Response]. Pokud pracujete s Nette, tento objekt je automaticky vytvořen frameworkem a můžete si jej nechat předat pomocí [dependency injection |dependency-injection:passing-dependencies]. V presenterech stačí jen zavolat metodu `$this->getHttpResponse()`.
 
 → [Instalace a požadavky |@home#Instalace]
 

http/cs/urls.texy

@@ -131,7 +131,7 @@ Url::removeDotSegments('./today/../file.txt');          // 'file.txt'
 UrlImmutable
 ============
 
-Třída [api:Nette\Http\UrlImmutable] je immutable (neměnnou) alternativou třídy `Url` (podobně jako je v PHP `DateTimeImmutable` neměnnou alternativou `DateTime`). Místo setterů má tzv. withery, které objekt nemění, ale vracejí nové instance s upravenou hodnotou:
+Třída [api:Nette\Http\UrlImmutable] je immutable (neměnnou) alternativou třídy [#Url] (podobně jako je v PHP `DateTimeImmutable` neměnnou alternativou `DateTime`). Místo setterů má tzv. withery, které objekt nemění, ale vracejí nové instance s upravenou hodnotou:
 
 ```php
 use Nette\Http\UrlImmutable;
@@ -230,7 +230,9 @@ $url->isEqual('https://nette.org');
 UrlScript
 =========
 
-Třída [api:Nette\Http\UrlScript] je potomkem `UrlImmutable` a navíc rozlišuje tyto další logické části URL:
+Třída [api:Nette\Http\UrlScript] je potomkem [#UrlImmutable] a rozšiřuje jej o další virtuální komponenty URL, jako je kořenový adresáři projektu apod. Stejně jako rodičovská třída je immutable (neměnným) objektem.
+
+Následující diagram zobrazuje komponenty, které UrlScript rozpoznává:
 
 /--pre
       baseUrl    basePath  relativePath  relativeUrl
@@ -242,6 +244,13 @@ Třída [api:Nette\Http\UrlScript] je potomkem `UrlImmutable` a navíc rozlišuj
                    scriptPath       pathInfo
 \--
 
+- `baseUrl` je základní URL adresa aplikace včetně domény a části cesty ke kořenovému adresáři aplikace
+- `basePath` je část cesty ke kořenovému adresáři aplikace
+- `scriptPath` je cesta k aktuálnímu skriptu
+- `relativePath` je název skriptu (případně další segmenty cesty) relativní k basePath
+- `relativeUrl` je celá část URL za baseUrl, včetně query string a fragmentu.
+- `pathInfo` dnes už málo využívaná část URL za názvem skriptu
+
 Pro vrácení částí URL jsou k dispozici metody:
 
 .[language-php]
@@ -254,4 +263,4 @@ Pro vrácení částí URL jsou k dispozici metody:
 | `getRelativeUrl(): string`	| `'script.php/pathinfo/?name=param#footer'`
 | `getPathInfo(): string`		| `'/pathinfo/'`
 
-Objekty `UrlScript` přímo nevytváříme, ale vrací jej metoda [Nette\Http\Request::getUrl()|request].
+Objekty `UrlScript` obvykle přímo nevytváříme, ale vrací jej metoda [Nette\Http\Request::getUrl()|request] s již správně nastavenými komponentami pro aktuální HTTP požadavek.

http/en/request.texy

@@ -4,9 +4,9 @@ HTTP Request
 .[perex]
 Nette encapsulates the HTTP request into objects with an understandable API while providing a sanitization filter.
 
-An HTTP request is an [api:Nette\Http\Request] object, which you get by passing it using [dependency injection |dependency-injection:passing-dependencies]. In presenters simply call `$httpRequest = $this->getHttpRequest()`.
+HTTP request is represented by the [api:Nette\Http\Request] object. If you work with Nette, this object is automatically created by the framework and you can have it passed to you using [dependency injection |dependency-injection:passing-dependencies]. In presenters, you just need to call the `$this->getHttpRequest()` method. If you work outside the Nette Framework, you can create the object using [RequestFactory|#RequestFactory].
 
-What is important is that Nette when [creating|#RequestFactory] this object, it clears all GET, POST and COOKIE input parameters as well as URLs of control characters and invalid UTF-8 sequences. So you can safely continue working with the data. The cleaned data is then used in presenters and forms.
+A major advantage of Nette is that when creating the object, it automatically sanitizes all input parameters GET, POST, COOKIE as well as URL from control characters and invalid UTF-8 sequences. You can then safely work with this data. The sanitized data is subsequently used in presenters and forms.
 
 → [Installation and requirements |@home#Installation]
 
@@ -199,28 +199,35 @@ echo $httpRequest->detectLanguage($langs); // en
 RequestFactory
 ==============
 
-The object of the current HTTP request is created by [api:Nette\Http\RequestFactory]. If you are writing an application that does not use a DI container, you create a request as follows:
+The [api:Nette\Http\RequestFactory] class is used to create an instance of `Nette\Http\Request`, which represents the current HTTP request. (If you work with Nette, the HTTP request object is automatically created by the framework.)
 
 ```php
 $factory = new Nette\Http\RequestFactory;
 $httpRequest = $factory->fromGlobals();
 ```
 
-RequestFactory can be configured before calling `fromGlobals()`. We can disable all sanitization of input parameters from invalid UTF-8 sequences using `$factory->setBinary()`. And also set up a proxy server, which is important for the correct detection of the user's IP address using `$factory->setProxy(...)`.
+The `fromGlobals()` method creates a request object based on the current PHP global variables (`$_GET`, `$_POST`, `$_COOKIE`, `$_FILES` and `$_SERVER`). When creating the object, it automatically cleanses all input parameters GET, POST, COOKIE as well as URL from control characters and invalid UTF-8 sequences, which ensures security when working with this data later.
 
-It's possible to clean up URLs from characters that can get into them because of poorly implemented comment systems on various other websites by using filters:
+RequestFactory can be configured before calling `fromGlobals()`:
+
+- using the method `$factory->setBinary()` you can disable automatic cleansing of input parameters from control characters and invalid UTF-8 sequences.
+- using the method `$factory->setProxy(...)` you specify the IP address of the [proxy server |configuration#HTTP proxy], which is necessary for correct detection of the user's IP address.
+
+RequestFactory allows you to define filters that automatically transform parts of the URL request. These filters remove unwanted characters from URLs that may have been inserted, for example, by incorrect implementation of comment systems on various websites:
 
 ```php
-// remove spaces from path
+// removing spaces from the path
 $requestFactory->urlFilters['path']['%20'] = '';
 
-// remove dot, comma or right parenthesis form the end of the URL
+// removing a period, comma, or right parenthesis from the end of the URI
 $requestFactory->urlFilters['url']['[.,)]$'] = '';
 
-// clean the path from duplicated slashes (default filter)
+// cleaning the path from double slashes (default filter)
 $requestFactory->urlFilters['path']['/{2,}'] = '/';
 ```
 
+The first key `'path'` or `'url'` determines which part of the URL the filter will be applied to. The second key is a regular expression to be searched for, and the value is the replacement to be used instead of the found text.
+
 
 Uploaded Files
 ==============

http/en/response.texy

@@ -4,7 +4,7 @@ HTTP Response
 .[perex]
 Nette encapsulates the HTTP response into objects with an understandable API while providing a sanitization filter.
 
-An HTTP response is an [api:Nette\Http\Response] object, which you get by passing it using [dependency injection |dependency-injection:passing-dependencies]. In presenters simply call `$httpResponse = $this->getHttpResponse()`.
+HTTP response is represented by the [api:Nette\Http\Response] object. If you work with Nette, this object is automatically created by the framework and you can have it passed to you using [dependency injection |dependency-injection:passing-dependencies]. In presenters, you just need to call the `$this->getHttpResponse()` method.
 
 → [Installation and requirements |@home#Installation]
 

http/en/urls.texy

@@ -131,7 +131,7 @@ Url::removeDotSegments('./today/../file.txt');          // 'file.txt'
 UrlImmutable
 ============
 
-The class [api:Nette\Http\UrlImmutable] is an immutable alternative to class `Url` (just as in PHP `DateTimeImmutable` is immutable alternative to `DateTime`). Instead of setters, it has so-called withers, which do not change the object, but return new instances with a modified value:
+The [api: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:
 
 ```php
 use Nette\Http\UrlImmutable;
@@ -230,7 +230,9 @@ $url->isEqual('https://nette.org');
 UrlScript
 =========
 
-The [api:Nette\Http\UrlScript] class is a descendant of `UrlImmutable` and additionally distinguishes these logical parts of the URL:
+The [api: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:
 
 /--pre
       baseUrl    basePath  relativePath  relativeUrl
@@ -242,6 +244,13 @@ The [api:Nette\Http\UrlScript] class is a descendant of `UrlImmutable` and addit
                    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:
 
 .[language-php]
@@ -254,5 +263,4 @@ The following methods are available to get these parts:
 | `getRelativeUrl(): string`	| `'script.php/pathinfo/?name=param#footer'`
 | `getPathInfo(): string`		| `'/pathinfo/'`
 
-
 We do not create objects `UrlScript` directly, but the method [Nette\Http\Request::getUrl() |request] returns it.