Merge pull request #9359 from bizley-code/guide-pl

Guide [PL] rest rate limiting and start forms [skip ci]

docs/guide-pl/rest-rate-limiting.md

@@ -0,0 +1,37 @@
+Limit użycia
+============
+
+W celu zapobiegnięcia nadużyciom, powinno się rozważyć wprowadzenie *limitu użycia* swojego API. Może to być na przykład ograniczenie 
+do maksymalnie 100 zapytań do API dla każdego użytkownika w czasie 10 minut. Jeśli użytkownik przekroczy ten limit w zadanym czasie, 
+należy zwrócić odpowiedź ze statusem 429 (oznaczającym "Zbyt dużo zapytań").
+
+Aby ustalić limit użycia, [[yii\web\User::identityClass|klasa identyfikująca użytkownika]] powinna zaimplementować [[yii\filters\RateLimitInterface]].
+Interfejs ten wymaga dodania trzech metod:
+
+* `getRateLimit()`: zwraca maksymalną liczbę zapytań i okres czasu (np. `[100, 600]` oznacza maksymalnie 100 zapytań do API w czasie 600 sekund).
+* `loadAllowance()`: zwraca liczbę pozostałych dozwolonych zapytań z limitu i uniksowy znacznik czasu wskazujący datę ostatniego sprawdzenia limitu.
+* `saveAllowance()`: zapisuje liczbę pozostałych dozwolonych zapytań i aktualny uniksowy znacznik czasu.
+
+Do celów obsługi powyższych metod można wykorzystać dwie dodatkowe kolumny w bazie danych użytkowników dla liczby dokonanych połączeń i znacznika czasu. 
+Po ustaleniu tych wartości, metody `loadAllowance()` i `saveAllowance()` mogą być poprawnie zaimplementowane do odczytu i zapisu tych wartości dla aktualnego 
+zautoryzowanego użytkownika. Aby zwiększyć wydajność tego mechanizmu, należy rozważyć użycie pamięci podręcznej lub bazy typu NoSQL.
+
+Po zaimplemetowaniu wymaganego interfejsu, Yii automatycznie użyje [[yii\filters\RateLimiter]], skonfigurowanego jako filtr akcji dla [[yii\rest\Controller]], 
+aby pilnować limitu użycia API. Mechanizm rzuci wyjątek [[yii\web\TooManyRequestsHttpException]], kiedy limit zostanie przekroczony. 
+
+Po dodaniu limitu, każda odpowiedź będzie domyślnie zawierała następujące nagłówki HTTP, zawierające informacje o aktualnym użyciu limitu:
+
+* `X-Rate-Limit-Limit`, maksymalna liczba zapytań w zadanym okresie czasu,
+* `X-Rate-Limit-Remaining`, liczba pozostałych dozwolonych zapytań z limitu w aktualnym okresie czasu,
+* `X-Rate-Limit-Reset`, liczba sekund, którą należy odczekać, aby uzyskać ponownie maksymalną liczbę zapytań z limitu.
+
+Wysyłanie powyższych nagłówków można wyłączyć konfigurując [[yii\filters\RateLimiter::enableRateLimitHeaders]] w klasie kontrolera REST jak w poniższym przykładzie.
+
+```php
+public function behaviors()
+{
+    $behaviors = parent::behaviors();
+    $behaviors['rateLimiter']['enableRateLimitHeaders'] = false;
+    return $behaviors;
+}
+```

docs/guide-pl/start-forms.md

@@ -0,0 +1,220 @@
+Praca z formularzami
+==================
+
+Ta sekcja opisuje jak utworzyć nową stronę z formularzem pobierającym dane od użytkownika.
+Strona będzie wyświetlała formularz z polami dwoma polami do uzupełnienia: `nazwa` oraz `email`.
+Po otrzymaniu tych dwóch danych od użytkownika, wyświetlimy spowrotem wprowadzone wartości w celu ich potwierdzenia.
+
+Aby to osiągnąć, oprócz utworzenia [akcji](structure-controllers.md) i dwóch [widoków](structure-views.md), będziesz musiał utworzyć [model](structure-models.md).
+
+W tym poradniku nauczysz się jak:
+
+* utworzyć [model](structure-models.md) reprezentujący dane wprowadzone przez użytkownika przez formularz,
+* zadeklarować zasady do sprawdzenia wprowadzonych danych,
+* zbudować formularz HTML w [widoku](structure-views.md).
+* build an HTML form in a [view](structure-views.md).
+
+
+Tworzenie modelu <span id="creating-model"></span>
+----------------
+
+Dane które pobierzemy od użytkownika będą reprezentowane przez klasę modelu `EntryForm`, która pokazana jest poniżej. Jest ona zapisana w pliku `models/EntryForm.php`.
+Po więcej szczegółów odnośnie konwencji nazewnictwa plików zajrzyj do sekcji[autoładowania klas](concept-autoloading.md)
+
+```php
+<?php
+
+namespace app\models;
+
+use Yii;
+use yii\base\Model;
+
+class EntryForm extends Model
+{
+    public $name;
+    public $email;
+
+    public function rules()
+    {
+        return [
+            [['name', 'email'], 'required'],
+            ['email', 'email'],
+        ];
+    }
+}
+```
+
+Klasa `EntryForm` rozszerza [[yii\base\Model]], podstawową klasę dostarczoną przez Yii, głównie używaną do reprezentowania danych z formularzy.
+
+> Info: [[yii\base\Model]] jest używane jako rodzic dla klasy modeli *NIE* powiązanych z tabelą bazy danych.
+[[yii\db\ActiveRecord]] jest rodzicem dla klas modeli powiązanych z tabelami bazy danych.
+
+Klasa `EntryForm` zawiera dwa elementy publiczne, `name` oraz `email`, które są używane do przechowania danych wprowadzonych przez użytkownika.
+Zawieta również metodą nazwaną `rules()`, która zwraca zestaw zasad do walidacji wprowadzonych danych. Zadeklarowane zasady oznaczają:
+
+* wartości w polach `name` oraz `email są wymagane
+* wartość pola `email` musi być prawidłowym adresem email
+
+Jeśli posiadasz uzupełniony obiekt `EntryForm` danymi wprowadzonymi przez użytkownika, możesz wywołać jego funkcję [[yii\base\Model::validate()|validate()]], aby uruchomić procedurę sprawdzania poprawności danych.
+W przypadku wystąpienia błędów w walidacji, wartość [[yii\base\Model::hasErrors|hasErrors]] zostanie ustawiona na `true`. Możesz zobaczyć jakie błędy wystąpiły za pomocą metody [[yii\base\Model::getErrors|errors]].
+
+```php
+<?php
+$model = new EntryForm();
+$model->name = 'Qiang';
+$model->email = 'bad';
+if ($model->validate()) {
+    // Dobrze!
+} else {
+    // Źle!
+    // Use $model->getErrors()
+}
+```
+
+
+Tworzenie akcji <span id="creating-action"></span>
+------------------
+
+Następnie musisz utworzyć akcję o nazwie `entry` w kontrolerze `site`,  która użyje Twojego nowego modelu. Proces tworzenia i używania akcji był wytłumaczony w sekcji [Witaj świecie](start-hello.md)
+
+```php
+<?php
+
+namespace app\controllers;
+
+use Yii;
+use yii\web\Controller;
+use app\models\EntryForm;
+
+class SiteController extends Controller
+{
+    // ...obecny kod...
+
+    public function actionEntry()
+    {
+        $model = new EntryForm();
+
+        if ($model->load(Yii::$app->request->post()) && $model->validate()) {
+            // walidacja otrzymanych danych w modelu
+
+            // zrób coś sensownego z modelem
+
+            return $this->render('entry-confirm', ['model' => $model]);
+        } else {
+            // w przypadku błędów walidacji wyświetlana jest strona z błędami
+            return $this->render('entry', ['model' => $model]);
+        }
+    }
+}
+```
+
+Akcja tworzy na początku obiekt `EntryForm`. Następnie próbuje uzupełnić model danymi ze zmiennej `$_POST`, dostarczanymi w Yii przez metodę [[yii\web\Request::post()]].
+Jeśli model został prawidłowo uzupełniony(np. jeśli użytkownik wysłał formularz HTML), akcja wywoła metodę [[yii\base\Model::validate()|validate()]] aby upewnić się, że wprowadzone dane są prawidłowe.
+
+> Info: Wyrażenie `Yii::$app` reprezentuje instancję [aplikacji](structure-applications.md), która jest globalnie dostępnym singletonem.
+Jest również [lokatorem usług](concept-service-locator.md), który dostarcza komponenty takie jak `request`, `response` lub `db` do wsparcia specyficznej funkcjonalności.
+W powyższym kodzie użyty jest komponent `request` aby uzyskać dostęp do danych w zmiennej `$_POST`.
+
+Jeśli wszystko jest w porządku, akcja wyrenderuje widok o nazwie `entry-confirm` w celu potwierdzenia prawidłowego przesłania danych przez użytkownika.
+Jeśli nie zostały wysłane żadne dane lub dane zawierają błędy, zostanie wyrenderowany widok `entry`, w którym będzie pokazany formularz HTML wraz z wiadomościami błędów walidacji.
+
+> Note: W tym prostym przykładzie po prostu renderujemy stronę z potwierdzeniem prawidłowego przesłania danych. W praktyce powinieneś rozważyć użycie [[yii\web\Controller::refresh()|refresh()]] lub [[yii\web\Controller::redirect()|redirect()]] aby uniknąć [problemów z ponownym przesłaniem formularza](http://en.wikipedia.org/wiki/Post/Redirect/Get).
+
+
+Tworzenie widoku <span id="creating-views"></span>
+--------------
+
+Na koniec, utwórz dwa pliki o nazwach `entry-confirm` oraz `entry`. Będą one renderowane przez akcję `entry`, tak jak to przed chwilą opisaliśmy.
+
+Widok `entry-confirm` wyświelta po prostu dane `name` oraz `email`. Powinien być zapisany w pliku `views/site/entry-confirm.php`.
+
+```php
+<?php
+use yii\helpers\Html;
+?>
+<p>Wpisałeś następujące informacje:</p>
+
+<ul>
+    <li><label>Nazwa</label>: <?= Html::encode($model->name) ?></li>
+    <li><label>Email</label>: <?= Html::encode($model->email) ?></li>
+</ul>
+```
+
+Widok `entry` wyświetla formularz HTML. Powinien być zapisany w pliku `views/site/entry.php`.
+
+```php
+<?php
+use yii\helpers\Html;
+use yii\widgets\ActiveForm;
+?>
+<?php $form = ActiveForm::begin(); ?>
+
+    <?= $form->field($model, 'name') ?>
+
+    <?= $form->field($model, 'email') ?>
+
+    <div class="form-group">
+        <?= Html::submitButton('Wyślij', ['class' => 'btn btn-primary']) ?>
+    </div>
+
+<?php ActiveForm::end(); ?>
+```
+
+Widok używa potężnego [widżetu](structure-widgets.md) nazwanego [[yii\widgets\ActiveForm|ActiveForm]] do budowania formularza HTML.
+Metody `begin()` oraz `end()` renderują odpowiednio otwierające i zamykające tagi formularza. Pomiędzy wywołaniami tych dwóch metod, pola do wprowadzania są tworzone przez metodę [[yii\widgets\ActiveForm::field()|field()]].
+Następnie, po polach do wprowadzania danych, wywoływana jest metoda [[yii\helpers\Html::submitButton()]] do wygenerowania przycisku "Wyślij", który wysyła formularz.
+
+
+Próba <span id="trying-it-out"></span>
+-------------
+
+Aby zobaczyć jak to działa, użyj przeglądarki aby przejść pod dany adres:
+
+```
+http://hostname/index.php?r=site/entry
+```
+
+Zobaczysz stronę wyświetlającą formularz z dwoma polami. Przed każdym polem znajduje się etykieta opisująca to pole. Jeśli klikniesz przycisk "Wyślij" nie wpisując żadnych danych, lub jeśli nie wprowadzisz prawidłowego adresu email, zobaczysz wiadomość błędu wyświeloną pod polem którego ona dotyczy.
+
+![Formularz z błędami walidacji](../guide/images/start-form-validation.png)
+
+Po wpisaniu prawidłowej nazwy, adresu email oraz kliknięciu przycisku "Wyślij", zobaczysz nową stronę wyświetlającą dane, które właśnie wprowadziłes.
+
+![Potwierdzenie](../guide/images/start-entry-confirmation.png)
+
+
+### "Wyjaśnienie magii" <span id="magic-explained"></span>
+
+Możesz się zastanawiać, jak działa ten formularz HTML, ponieważ wydaje się prawie magicznym to, że wyświetla etykietę do każdego pola oraz wyświetla komunikat błędu, jeśli wprowadzisz błędne dane, bez przeładowania strony.
+
+Wstępna walidacja jest wykonywana po stronie klienta używając JavaScript'u, kolejnie dopiero po stronie serwera przez PHP.
+[[yii\widgets\ActiveForm]] potrafi wyodrębnić zasady walidacji, które zadeklarowałeś w `EntryForm`, przekształcić je w wykonywalny kod JavaScript oraz użyć go do walidacji danych. 
+Jeśli zablokowałeś JavaScript w swojej przeglądarce, walidacja wciąż będzie wykonywana po stronie serwera, jak pokazano w metodzie `actionEntry()`. 
+Gwarantuje to prawidłowość danych w każdych okolicznościach.
+
+> Warning: Walidacja po stronie klienta jest opcją, która zapewnia lepsze doświadczenia dla użytkownika. Walidacja po stronie serwera jest zawsze wymagana, niezależnie czy walidacja po stronie klienta jest włączona, czy nie.
+
+Etykiety dla pól w formularzu generowane są przy pomocy metody `field()`, używającej nazw właściwości z modelu.
+Dla przykładu, etykieta `Name` zostanie wygenerowana dla właściwości `name`.
+
+Możesz dostosowywać etykiety w widoku, używając poniższego kodu:
+
+```php
+<?= $form->field($model, 'name')->label('Your Name') ?>
+<?= $form->field($model, 'email')->label('Your Email') ?>
+```
+
+> Info: Yii dostarcza wiele podobnych widżetów, które pomogą Ci szybko tworzyć złożone i dynamiczne widoki.
+Tak jak nauczysz się później, pisanie nowego widżetu jest ekstremalnie łatwe. 
+Będziesz mógł przekształcić Twój kod widoku na widżet do wielokrotnego użytku, aby uprościć rozwój swoich widoków w przyszłości.
+
+
+Podsumowanie <span id="summary"></span>
+-------
+
+W tej sekcji poradnika dotknęliśmy każdej części struktury MVC. Nauczyłeś się jak utworzyć klasę modelu, aby reprezentowała dane użytkownika oraz je walidowała.
+
+Nauczyłeś się także, jak pobierać dane od użytkowników oraz jak wyświetlać pobrane dane w przeglądarce. 
+To zadanie mogłoby zabrać Ci wiele czasu podczas pisania aplikacji, jednak Yii dostarcza wiele widżetów, które bardzo je ułatwiają.
+
+W następnej sekcji nauczysz się pracy z bazą danych, która jest wymagana w niemalże każdej aplikacji.

docs/guide-pl/start-gii.md

@@ -1,4 +1,4 @@
-Generowanie kodu w Gii
+Generowanie kodu za pomocą Gii
 ========================
 
 Ta sekcja opisuje jak używać [Gii](https://github.com/yiisoft/yii2-gii/blob/master/docs/guide/README.md) do automatycznego generowania kodu, który implementuje podstawowe funkcjonalności do aplikacji Web.