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

Components concept and REST routing PL [skip ci]

docs/guide-pl/README.md

@@ -63,8 +63,8 @@ Kluczowe koncepcje
 
 * [Komponenty](concept-components.md)
 * [Właściwości](concept-properties.md)
-* [Events](concept-events.md)
-* [Behaviors](concept-behaviors.md)
+* [Eventy](concept-events.md)
+* [Behaviory](concept-behaviors.md)
 * [Konfiguracje](concept-configurations.md)
 * [Aliasy](concept-aliases.md)
 * [Autoładowanie klas](concept-autoloading.md)

docs/guide-pl/concept-components.md

@@ -0,0 +1,93 @@
+Komponenty
+==========
+
+Komponenty są głównym budulcem aplikacji Yii. Komponenty to instancje klasy [[yii\base\Component]] lub jej potomnych. 
+Trzy główne funkcjonalności, które zapewniają komponenty innym klasom to:
+
+* [Właściwości](concept-properties.md)
+* [Eventy (zdarzenia)](concept-events.md)
+* [Behaviory (zachowania)](concept-behaviors.md)
+ 
+Wszystkie razem i każda z tych funkcjonalności osobno zapewnia klasom Yii o wiele większą elastyczność i łatwość użycia. Dla przykładu,
+dołączony [[yii\jui\DatePicker|widżet wybierania daty]], komponent interfejsu użytkownika, może być użyty w [widoku](structure-view.md), 
+aby wygenerować interaktywny kalendarz:
+
+```php
+use yii\jui\DatePicker;
+
+echo DatePicker::widget([
+    'language' => 'pl',
+    'name'  => 'country',
+    'clientOptions' => [
+        'dateFormat' => 'yy-mm-dd',
+    ],
+]);
+```
+
+Właściwości widżetu są w łatwy sposób konfigurowalne ponieważ jego klasa rozszerza [[yii\base\Component]].
+
+Komponenty zapewniają duże możliwości, ale przez to są też bardziej zasobożerne od standardowych obiektów, ponieważ wymagają dodatkowej pamięci i czasu CPU dla wsparcia 
+[eventów](concept-events.md) i [behaviorów](concept-behaviors.md) w szczególności.
+Jeśli komponent nie wymaga tych dwóch funkcjonalności, należy rozważyć rozszerzenie jego klasy z [[yii\base\Object]] zamiast [[yii\base\Component]]. 
+Dzięki temu komponent będzie tak samo wydajny jak standardowy obiekt PHP, ale z dodatkowym wsparciem [właściwości](concept-properties.md).
+
+Rozszerzając klasę [[yii\base\Component]] lub [[yii\base\Object]], zalecane jest aby przestrzegać następującej konwencji:
+
+- Przeciążając konstruktor, dodaj parametr `$config` jako *ostatni* na liście jego argumentów i przekaż go do konstruktora rodzica.
+- Zawsze wywoływuj konstruktor rodzica *na końcu* przeciążanego konstruktora.
+- Przeciążając metodę [[yii\base\Object::init()]], upewnij się, że wywołujesz metodę `init` rodzica *na początku* własnej implementacji metody `init`.
+
+Przykład:
+
+```php
+<?php
+
+namespace yii\components\MyClass;
+
+use yii\base\Object;
+
+class MyClass extends Object
+{
+    public $prop1;
+    public $prop2;
+
+    public function __construct($param1, $param2, $config = [])
+    {
+        // ... inicjalizacja przed zaaplikowaniem konfiguracji
+
+        parent::__construct($config);
+    }
+
+    public function init()
+    {
+        parent::init();
+
+        // ... inicjalizacja po zaaplikowaniu konfiguracji
+    }
+}
+```
+
+Postępowanie zgodnie z tymi zasadami zapewni [konfigurowalność](concept-configurations.md) Twojego komponentu, kiedy już zostanie utworzony. Dla przykładu:
+
+```php
+$component = new MyClass(1, 2, ['prop1' => 3, 'prop2' => 4]);
+// lub alternatywnie
+$component = \Yii::createObject([
+    'class' => MyClass::className(),
+    'prop1' => 3,
+    'prop2' => 4,
+], [1, 2]);
+```
+
+> Info: Wersja z wywołaniem [[Yii::createObject()]] wygląda na bardziej skomplikowaną, ale jest o wiele wydajniejsza, ponieważ jej implementację zapewnia 
+> [kontener wstrzykiwania zależności](concept-di-container.md).
+  
+
+Klasa [[yii\base\Object]] wymusza następujący cykl życia obiektu:
+
+1. Preinicjalizacja w konstruktorze. W tym miejscu można ustawić domyślne wartości właściwości.
+2. Konfiguracja obiektu poprzez `$config`. Konfiguracja może nadpisać domyślne wartości ustawione w konstruktorze.
+3. Postinicjalizacja w metodzie [[yii\base\Object::init()|init()]]. Metoda może być przeciążona w celu normalizacji i sanityzacji właściwości.
+4. Wywołanie metody obiektu.
+
+Pierwsze trzy kroki są w całości wykonywane w konstruktorze obiektu, co oznacza, że uzyskana instancja klasy jest już poprawnie zainicjowana i stabilna.

docs/guide-pl/rest-routing.md

@@ -0,0 +1,90 @@
+Routing
+=======
+
+Po przygotowaniu klas zasobów i kontrolerów dostęp do nich można uzyskać w ten sam sposób, jak w przypadku zwykłej aplikacji, używając URL np. 
+`http://localhost/index.php?r=user/create`.
+
+W praktyce zwykle chcemy skorzystać z opcji "ładnych" URLi i metod HTTP.
+Przykładowo żądanie `POST /users` może oznaczać wywołanie akcji `user/create`, co możemy uzyskać w łatwy sposób konfigurując 
+[komponent aplikacji](structure-application-components.md) `urlManager` w pliku konfiguracyjnym jak poniżej:
+
+```php
+'urlManager' => [
+    'enablePrettyUrl' => true,
+    'enableStrictParsing' => true,
+    'showScriptName' => false,
+    'rules' => [
+        ['class' => 'yii\rest\UrlRule', 'controller' => 'user'],
+    ],
+]
+```
+
+Porównując to z menadżerem URLi dla aplikacji Web, główną nowością tutaj jest użycie [[yii\rest\UrlRule]] do routingu RESTfulowych zasobów API. 
+Ta specjalna klasa zasad URL stworzy cały zestaw potomnych zasad URL obsługujących routing i tworzenie URLi dla wyznaczonego kontrolera.
+Dla przykładu, kod powyżej jest zgrubnym odpowiednikiem następujących zasad:
+
+```php
+[
+    'PUT,PATCH users/<id>' => 'user/update',
+    'DELETE users/<id>' => 'user/delete',
+    'GET,HEAD users/<id>' => 'user/view',
+    'POST users' => 'user/create',
+    'GET,HEAD users' => 'user/index',
+    'users/<id>' => 'user/options',
+    'users' => 'user/options',
+]
+```
+
+I poniższe punkty końcowe API są obsługiwane przez tę zasadę:
+
+* `GET /users`: lista wszystkich użytkowników strona po stronie;
+* `HEAD /users`: pokazuje streszczenie informacji listy użytkowników;
+* `POST /users`: tworzy nowego użytkownika;
+* `GET /users/123`: zwraca szczegóły na temat użytkownika 123;
+* `HEAD /users/123`: zwraca streszczenie informacji o użytkowniku 123;
+* `PATCH /users/123` i `PUT /users/123`: aktualizuje użytkownika 123;
+* `DELETE /users/123`: usuwa użytkownika 123;
+* `OPTIONS /users`: pokazuje obsługiwane metody dla punktu końcowego `/users`;
+* `OPTIONS /users/123`: pokazuje obsługiwane metody dla punktu końcowego `/users/123`.
+
+Możesz skonfigurować opcje `only` i `except`, aby wskazać listę akcji, które mają być odpowiednio: tylko obsługiwane lub pominięte.
+Przykładowo,
+
+```php
+[
+    'class' => 'yii\rest\UrlRule',
+    'controller' => 'user',
+    'except' => ['delete', 'create', 'update'],
+],
+```
+
+Dodatkowo można dodać opcję `patterns` lub `extraPatterns`, aby zredefiniować istniejące wzorce lub dodać nowe obsługiwane przez tę zasadę.
+Dla przykładu, aby dodać obsługę nowej akcji `search` dla punktu końcowego `GET /users/search`, skonfiguruj opcję `extraPatterns` jak następuje,
+
+```php
+[
+    'class' => 'yii\rest\UrlRule',
+    'controller' => 'user',
+    'extraPatterns' => [
+        'GET search' => 'search',
+    ],
+]
+```
+
+Na pewno zwróciłeś uwagę na to, że ID kontrolera `user` występuje tu w formie mnogiej jako `users` dla URLi punktu końcowego.
+Dzieje się tak, ponieważ [[yii\rest\UrlRule]] automatycznie przechodzi na formę mnogą dla ID kontrolerów podczas tworzenia potomnych zasad URL.
+Zachowanie to można wyłączyć ustawiając [[yii\rest\UrlRule::pluralize]] na false. 
+
+> Info: forma mnoga ID kontrolerów jest tworzona poprzez metodę [[yii\helpers\Inflector::pluralize()]]. Uwzględnia ona specjalne zasady tworzenia form mnogich. 
+  Dla przykładu, od słowa `box` zostanie utworzona liczba mnoga `boxes` a nie `boxs`.
+
+W przypadku, gdy mechanizm automatycznego tworzenia formy mnogiej nie spełnia Twoich oczekiwań, możesz również skonfigurować właściwość 
+[[yii\rest\UrlRule::controller]], aby bezpośrednio określić w jaki sposób nazwa użyta w punkcie końcowym URLi ma być zmapowana na ID kontrolera. 
+Dla przykładu, poniższy kod mapuje nazwę `u` na ID kontrolera `user`.  
+ 
+```php
+[
+    'class' => 'yii\rest\UrlRule',
+    'controller' => ['u' => 'user'],
+]
+```