Autoloading tutorial translated and added

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@21771 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/pl/tutorials/autoloading-conclusion.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- EN-Revision: 19778 -->
+<!-- Reviewed: no -->
+<sect1 id="learning.autoloading.conclusion">
+    <title>Podsumowanie</title>
+
+    <para>
+        Zend Framework zachęca do stosowanie automatycznego ładowania plików a nawet korzysta z
+        niego w domyślnej konfiguracji poprzez <classname>Zend_Application</classname>. Powyższy
+        samouczek przedstawia informacje niezbędne do pomyślnego użycia klasy
+        <classname>Zend_Loader_Autoloader</classname> jak i do rozszerzenia jego możliwości o 
+        własne metody automatycznego dołączania plików i zasobów.
+    </para>
+
+    <para>
+        Aby uzyskać więcej informacji należy zapoznać się z dokumentacją
+        <link linkend="zend.loader.autoloader">Zend_Loader_Autoloader</link> oraz
+        <link linkend="zend.loader.autoloader-resource">Zend_Loader_Autoloader_Resource</link>.
+    </para>
+</sect1>

documentation/manual/pl/tutorials/autoloading-design.xml

@@ -0,0 +1,112 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- EN-Revision: 20115 -->
+<!-- Reviewed: no -->
+<sect1 id="learning.autoloading.design">
+    <title>Cele i budowa</title>
+
+    <sect2 id="learning.autoloading.design.naming">
+        <title>Konwencja nazewnictwa klas</title>
+
+        <para>
+            Aby zrozumieć autoloader w Zend Framework, należy najpierw zrozumieć połączenie
+            pomiędzy nazwami klas a ich plikami. 
+        </para>
+
+        <para>
+            Budując Zend Framework zapożyczono ideę organizacji klas z biblioteki
+            <ulink url="http://pear.php.net/">PEAR</ulink>. Według niej relacja klas do plików
+            wynosi 1:1. W skrócie: aby odnaleźć ścieżkę do odpowiedniego pliku
+            znak podkreślenia ("_") w nazwach klas jest zastępowany znakiem oddzielenia katalogu
+            a następnie dodawane jest rozszerzenie "<filename>.php</filename>". Przykładowo,
+            klasa "<classname>Foo_Bar_Baz</classname>" odpowiadałaby ścieżce dostępu
+            "<filename>Foo/Bar/Baz.php</filename>". Dodatkowo respektowane są ustawienia
+            zmiennej konfiguracyjnej <acronym>PHP</acronym> - <property>include_path</property>,
+            dzięki czemu możliwe jest użycie <methodname>include()</methodname> oraz
+            <methodname>require()</methodname> i wyszukanie pliku wg. ścieżki względnej do katalogów
+            w <property>include_path</property>.
+        </para>
+
+        <para>
+            Dodatkowo, podobnie jak <acronym>PEAR</acronym> oraz
+            <ulink url="http://php.net/userlandnaming.tips">projekt PHP</ulink> praktykowane i
+            zalecane jest użycie w kodzie prefiksów charakterystycznych dla projektu lub producenta.
+            To oznacza, że wszystkie klasy powinny dzielić jeden wspólny prefiks. Przykładowo,
+            wszystkie klasy w Zend Framework mają prefiks "Zend_". Taka konwencja chroni
+            przed kolizjami nazw. W ramach Zend Framework przybiera to nazwę prefiksu przestrzeni
+            nazw. Należy zachować ostrożność aby nie pomylić tego z natywną obsługą przestrzeni
+            nazw w <acronym>PHP</acronym>.
+        </para>
+
+        <para>
+            Zend Framework podąża za tymi wskazówkami wewnętrznie ale nasze standardy zachęcają 
+            do ich stosowania także w kodzie aplikacji, innych bibliotek itp.
+        </para>
+    </sect2>
+
+    <sect2 id="learning.autoloading.design.autoloader">
+        <title>Konwencja nazewnictwa i budowa autoloadera</title>
+
+        <para>
+            Obsługa autoloadera w Zend Framework udostępniona głównie poprzez
+            <classname>Zend_Loader_Autoloader</classname> charakteryzuje się poniższymi celami
+            i elementami budowy:
+        </para>
+
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <emphasis>Zapewnia przeszukiwanie przestrzeni nazw</emphasis>.
+                    Jeśli prefiks przestrzeni nazw klasy nie znajduje się na liście zarejestrowanych
+                    przestrzeni - od razu zwracana jest wartość <constant>FALSE</constant>.
+                    Dzięki temu może nastąpić szybsze przełączenie do ewentualnego kolejnego
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis>Umożliwienie działania autoloadera jako ostatniej instancji</emphasis>.
+                    W przypadku, gdy zespół programistów jest w dużym stopniu rozproszony lub
+                    lista respektowanych prefiksów przestrzeni nazw jest zmienna, autoloader
+                    powinien zachować swoją funkcjonalność w taki sposób, żeby możliwe było
+                    użycie każdego prefiksu przestrzeni nazw. Trzeba zwrócić uwagę na fakt, iż
+                    takie zachowanie nie jest zalecane i może prowadzić do 
+                    niepotrzebnego wydłużenia procesu wyszukania pliku.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis>Umożliwienie włączaniania i wyłączania raportowania błędów</emphasis>.
+                    Twórcy ZF - jak i większa część społeczności <acronym>PHP</acronym> - uważają,
+                    że zapobieganie raportowaniu błędów jest złym pomysłem. Jest kosztowne i
+                    powoduje ukrycie realnych problemów aplikacji. Domyślnie opcja ta powinna być
+                    wyłączona ale jeśli deweloper <emphasis>chce</emphasis> ją włączyć to jest to
+                    umożliwione.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis>Umożliwienie skonfigurowania własnych funkcji oferujących 
+                    funkcjonalność autoloadera</emphasis>.
+                    Część deweloperów nie będzie chciała używać
+                    <methodname>Zend_Loader::loadClass()</methodname> jednocześnie nie rezygnując
+                    z mechanizmów Zend Framework.
+                    Klasa <classname>Zend_Loader_Autoloader</classname> umożliwia wyszczególnienie
+                    alternatywnej funkcji oferującej taką samą funkcjonalność.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis>Umożliwienie manipulacji łańcuchem funkcji autoload w
+                    <acronym>SPL</acronym></emphasis>.
+                    Celem tego założenia jest pozwolenie na określenie przez dewelopera dodatkowych
+                    funkcji oferujących funkcjonalność autoloadera - np. dla funkcje ładujące
+                    zasoby dla klas, które nie mają relacji 1:1 z plikami - aby były zarejestrowane
+                    przed lub po domyślnym mechaniźmie autoloadera Zend Framework. 
+                </para>
+            </listitem>
+        </itemizedlist>
+    </sect2>
+</sect1>

documentation/manual/pl/tutorials/autoloading-intro.xml

@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- EN-Revision: 19782 -->
+<!-- Reviewed: no -->
+<sect1 id="learning.autoloading.intro">
+    <title>Wprowadzenie</title>
+
+    <para>
+        Autoloader to mechanizm, który eliminuje potrzebę ręcznego dołączania
+        plików w kodzie <acronym>PHP</acronym>. Według
+        <ulink url="http://php.net/autoload">dokumentacji autoloadera PHP</ulink> po skonfigurowaniu
+        autoloadera, będzie on uruchomiony automatycznie w sytuacji, w której zajdzie
+        próba użycia niezdefiniowanej klasy bądź interfejsu.
+    </para>
+
+    <para>
+        Dzięki autoloaderowi nie trzeba się zastanawiać <emphasis>gdzie</emphasis> znajduje się
+        plik z definicją danej klasy. Dobrze zdefiniowany autoloader uwalnia od potrzeby brania pod
+        uwagę lokalizacji pliku z klasą w stosunku do bieżącego pliku. Dzięki temu można po prostu
+        użyć klasy a autoloader zajmie się znalezieniem odpowiedniego pliku.
+    </para>
+
+    <para>
+        Dodatkowo, dzięki temu procesowi, poprzez odłożenie operacji ładowania pliku do ostatniej
+        możliwej chwili, można mieć pewność, że operacja wyszukania pliku zajdzie dokładnie
+        jeden raz. To może stanowić znakomite zwiększenie wydajności - w szczególności jeśli
+        wywołania do funkcji <methodname>require_once()</methodname> zostaną usunięte.
+    </para>
+
+    <para>
+        Zend Framework propaguje użycie autoloadera i udostępnia szereg narzędzi służących do
+        automatycznego dołączania bibliotek jak i kodu samej aplikacji. Niniejszy tutorial opisuje
+        te narzędzia jak i sposób ich efektywnego użycia.
+    </para>
+</sect1>

documentation/manual/pl/tutorials/autoloading-resources.xml

@@ -0,0 +1,107 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- EN-Revision: 19782 -->
+<!-- Reviewed: no -->
+<sect1 id="learning.autoloading.resources">
+    <title>Automatyczne ładowanie zasobów</title>
+
+    <para>
+        Często, podczas tworzenia aplikacji, zachowanie zalecanego przez Zend Framework standardu
+        dotyczącego utrzymania stosunku 1:1 pomiędzy klasami a plikami jest trudne bądź niekorzystne
+        z punktu widzenia wydajności. To oznacza, że pliki z klasami nie zostaną odnalezione przez
+        autoloader.
+    </para>
+
+    <para>
+        Zgodnie z <link linkend="learning.autoloading.design">celami autoloadera</link> a zwłaszcza
+        z ostatnim punktem, powyższa sytuacja jest obsługiwana przez autoloader Zend Framework
+        poprzez <classname>Zend_Loader_Autoloader_Resource</classname>.
+    </para>
+
+    <para>
+        Zasób to jedynie nazwa odpowiadająca przestrzeni nazw komponentu (dołączona do przestrzeni
+        nazw autoloadera) wraz ze ścieżką (relatywnie do ścieżki bazowej autoloadera). W praktyce
+        można użyć następującego kodu:
+    </para>
+
+    <programlisting language="php"><![CDATA[
+$loader = new Zend_Application_Module_Autoloader(array(
+    'namespace' => 'Blog',
+    'basePath'  => APPLICATION_PATH . '/modules/blog',
+));
+]]></programlisting>
+
+    <para>
+        Po włączeniu autoloadera należy "poinformować" go o typach zasobów, które powinien dołączać.
+        Są to, po prostu, pary względnych ścieżek oraz prefiksów.
+    </para>
+
+    <para>
+        Jako przykład może posłużyć następujące drzewo katalogów:
+    </para>
+
+    <programlisting language="text"><![CDATA[
+sciezka/do/zasobow/
+|-- forms/
+|   `-- Guestbook.php        // Foo_Form_Guestbook
+|-- models/
+|   |-- DbTable/
+|   |   `-- Guestbook.php    // Foo_Model_DbTable_Guestbook
+|   |-- Guestbook.php        // Foo_Model_Guestbook
+|   `-- GuestbookMapper.php  // Foo_Model_GuestbookMapper
+]]></programlisting>
+
+    <para>
+        Pierwszym krokiem jest utworzenie autoloadera zasobów:
+    </para>
+
+    <programlisting language="php"><![CDATA[
+$loader = new Zend_Loader_Autoloader_Resource(array(
+    'basePath'  => 'sciezka/do/zasobow/',
+    'namespace' => 'Foo',
+));
+]]></programlisting>
+
+    <para>
+        Następnie należy zdefiniować typy zasobów.
+        <methodname>Zend_Loader_Autoloader_Resourse::addResourceType()</methodname> przyjmuje trzy
+        argumenty: typ zasobu (dowolny łańcuch znaków), ścieżka relatywna do
+        ścieżki bazowej autoloadera, w której zasób się znajduje oraz prefiks używany przez dany typ
+        zasobu. W powyższym przykładzie istnieją trzy rodzaje zasobów: formularze (w katalogu
+        "forms" z prefiksem "Form"), modele (w katalogu "models" z prefiksem "Model") oraz modele
+        tabeli bazy danych (w katalogu "<filename>models/DbTable</filename>" z prefiksem
+        "<classname>Model_DbTable</classname>"). Następujący przykład pokazuje sposób ich
+        definiowania:
+    </para>
+
+    <programlisting language="php"><![CDATA[
+$loader->addResourceType('form', 'forms', 'Form')
+       ->addResourceType('model', 'models', 'Model')
+       ->addResourceType('dbtable', 'models/DbTable', 'Model_DbTable');
+]]></programlisting>
+
+    <para>
+        Po zdefiniowaniu, można używać tych klas bez ręcznego dołączania:
+    </para>
+
+    <programlisting language="php"><![CDATA[
+$form      = new Foo_Form_Guestbook();
+$guestbook = new Foo_Model_Guestbook();
+]]></programlisting>
+
+    <note>
+        <title>automatyczne ładowanie zasobu modułu</title>
+
+        <para>
+            Implementacja wzorca projektowego <acronym>MVC</acronym> w Zend Framework zachęca do
+            używania modułów, które są mini-aplikacjami w ramach tworzonego programu. Moduły
+            przeważnie posiadają wiele typów zasobów a Zend Framework nawet 
+            <link linkend="project-structure.filesystem">zaleca standardową strukturę katalogów
+            dla modułu</link>. Autoloader zasobów staje się bardzo przydatny w tym kontekście.
+            Przez to, jeśli umieści się plik z klasą bootstrap pochodną do
+            <classname>Zend_Application_Module_Bootstrap</classname> to autoloader zostanie
+            domyślnie włączony. Aby uzyskać więcej informacji należy zapoznać się z 
+            <link linkend="zend.loader.autoloader-resource.module"> dokumentacją
+            Zend_Loader_Autoloader_Module</link>.
+        </para>
+    </note>
+</sect1>

documentation/manual/pl/tutorials/autoloading-usage.xml

@@ -0,0 +1,167 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- EN-Revision: 19782 -->
+<!-- Reviewed: no -->
+<sect1 id="learning.autoloading.usage">
+    <title>Podstawowe użycie autoloadera</title>
+
+    <para>
+        Po krótkim opisie samej idei autoloadera jak i konwencji oraz celi związanych z
+        jego implementacją w Zend Framework można przejść do opisu użycia
+        <classname>Zend_Loader_Autoloader</classname>.
+    </para>
+
+    <para>
+        W najprostszym przypadku należy dołączyć plik z definicją klasy i uzyskać dostęp do obiektu.
+        <classname>Zend_Loader_Autoloader</classname> jest singletonem (co jest uwarunkowane
+        autoloaderem <acronym>SPL</acronym>, który jest pojedynczym zasobem) więc do uzyskania
+        jego instancji należy użyć metody <methodname>getInstance()</methodname>.
+    </para>
+
+    <programlisting language="php"><![CDATA[
+require_once 'Zend/Loader/Autoloader.php';
+Zend_Loader_Autoloader::getInstance();
+]]></programlisting>
+
+    <para>
+        Domyślnie spowoduje to automatyczne dołączanie dowolnych klas zawierających prefiks 
+        przestrzeni nazw "Zend_" oraz "ZendX_" pod warunkiem, że znajdują się w katalogu zawartym w
+        <property>include_path</property>.
+    </para>
+
+    <para>
+        Co sie dzieje w przypadku gdy wymagane jest użycie innych przestrzeni nazw? Najlepszym i
+        najłatwiejszym sposobem jest wywołanie metody <methodname>registerNamespace()</methodname>.
+        Można do niej przekazać pojedynczy prefiks przestrzeni nazw lub ich całą tablicę:
+    </para>
+
+    <programlisting language="php"><![CDATA[
+require_once 'Zend/Loader/Autoloader.php';
+$loader = Zend_Loader_Autoloader::getInstance();
+$loader->registerNamespace('Foo_');
+$loader->registerNamespace(array('Foo_', 'Bar_'));
+]]></programlisting>
+
+    <para>
+        Alternatywnie można skonfigurować <classname>Zend_Loader_Autoloader</classname> aby działał
+        jako autoloader awaryjny ("fallback" autoloader). To oznacza, że będzie próbował
+        działać dla każdej używanej klasy niezależnie od jej prefiksu przestrzeni nazw.
+    </para>
+
+    <programlisting language="php"><![CDATA[
+$loader->setFallbackAutoloader(true);
+]]></programlisting>
+
+    <warning>
+        <title>Nie należy używać autoloadera awaryjnego</title>
+
+        <para>
+            Użycie <classname>Zend_Loader_Autoloader</classname> jako autoloadera awaryjnego może
+            być kuszące ale nie jest rekomendowane.
+        </para>
+
+        <para>
+            Wewnętrznie <classname>Zend_Loader_Autoloader</classname> używa
+            <methodname>Zend_Loader::loadClass()</methodname> do dołączania definicji klas. Ta
+            metoda używa <methodname>include()</methodname> do załadowania danego pliku z klasą.
+            Funkcja <methodname>include()</methodname> zwraca wartość <constant>FALSE</constant>
+            w przypadku niepowodzenia a dodatkowo wysyła błąd ostrzeżenia <acronym>PHP</acronym> co
+            może prowadzić do następujących konsekwencji:
+        </para>
+
+        <itemizedlist>
+            <listitem>
+                <para>
+                    Jeśli włączona jest opcja <property>display_errors</property> to ostrzeżenie
+                    zostanie dołączone do wyniku działania funkcji.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    W zależności od wybranego poziomu opcji <property>error_reporting</property>
+                    może powodować bałagan w logach.
+                </para>
+            </listitem>
+        </itemizedlist>
+
+        <para>
+            Istnieje możliwość wyłączenia wyświetlania komunikatów błędów przez autoloader
+            (opisana w dokumentacji <classname>Zend_Loader_Autoloader</classname>) ale należy
+            pamiętać iż działa to tylko w przypadku włączenia opcji
+            <property>display_errors</property>. Plik z logami błędów i tak będzie przechowywał
+            wszystkie komunikaty. Z tego powodu zalecane jest używanie prefiksów przestrzeni nazw
+            i powiadomienie o nich autoloadera.
+        </para>
+    </warning>
+
+    <note>
+        <title>Prefiksy przestrzeni nazw a przestrznie nazw PHP</title>
+
+        <para>
+            W momencie powstawania tego dokumentu istnieje stabilna wersja
+            <acronym>PHP</acronym> 5.3. Od tego wydania <acronym>PHP</acronym> oficjalnie oferuje
+            pełne wsparcie dla przestrzeni nazw.
+        </para>
+
+        <para>
+            Zend Framework uprzedził <acronym>PHP</acronym> 5.3 pod tym względem.
+            Wewnątrz dokumentacji Zend Framework, jeśli jest mowa o "przestrzeniach nazw" to
+            odnosi się to do prefiksów klas wskazujących na aplikację, twórcę lub firmę.
+            Dla przykładu, wszystkie nazwy klas w Zend Framework mają prefiks "Zend_" - to jest
+            "przestrzeń nazw" używana przez firmę Zend.
+        </para>
+
+        <para>
+            Planowane jest wprowadzenie obsługi natywnych przestrzeni nazw <acronym>PHP</acronym>
+            do autoloadera w przyszłych wersjach Zend Framework. Będzie to możliwe od wersji 2.0.0.
+        </para>
+    </note>
+
+    <para>
+        Jeśli deweloper posiada własny autoloader (np. pochodzący z innej biblioteki, która jest
+        używana równolegle), który powinien zostać użyty z Zend Framework to można to uczynić za
+        pomocą metod klasy <classname>Zend_Loader_Autoloader</classname> o nazwach
+        <methodname>pushAutoloader()</methodname> oraz <methodname>unshiftAutoloader()</methodname>.
+        Powyższe metody dopiszą podane funkcje do listy autoloaderów (która jest uruchamiana przed
+        wewnętrznymi mechanizmami Zend Framework) odpowiednio na koniec bądź na początek.
+        Takie podejście oferuje następujące korzyści:
+    </para>
+
+    <itemizedlist>
+        <listitem>
+            <para>
+                Każda z tych metod przyjmuje drugi, opcjonalny argument - prefiks przestrzeni nazw.
+                Można go użyć do wskazania aby podany autoloader był uzywany jedynie do dołączania
+                klas zawierających podany prefiks. Jeśli dana klasa go nie posiada to autoloader nie
+                zostanie uruchomiony - takie podejście może znacznie zwiększyć wydajność. 
+            </para>
+        </listitem>
+
+        <listitem>
+            <para>
+                Jeśli zajdzie potrzeba manipulowania rejestrem funkcji
+                <methodname>spl_autoload()</methodname>, każdy autoloader, który stanowi
+                odwołanie do metody klasy może powodować problemy. Dzieje się tak ponieważ funkcja
+                <methodname>spl_autoload_functions()</methodname> nie zwraca tych samych instancji
+                obiektów (tylko ich kopie).
+                <classname>Zend_Loader_Autoloader</classname> nie posiada takich wad.
+            </para>
+        </listitem>
+    </itemizedlist>
+
+    <para>
+        W powyższy sposób można użyć każdego poprawnego odwołania do funkcji <acronym>PHP</acronym>
+        
+        Autoloaders managed this way may be any valid <acronym>PHP</acronym> callback.
+    </para>
+
+    <programlisting language="php"><![CDATA[
+// Dołączenie funkcji 'my_autoloader', która zajmuje się klasami
+// z prefiksem 'My_' na koniec listy autoloaderów
+$loader->pushAutoloader('my_autoloader', 'My_');
+
+// Dołączenie statycznej metody Foo_Loader::autoload(), która zajmuje
+// się klasami z prefiksem 'Foo_' na początek listy autoloaderów
+$loader->unshiftAutoloader(array('Foo_Loader', 'autoload'), 'Foo_');
+]]></programlisting>
+</sect1>