Development

Documentation/pl_PL/book/1.0/17-Extending-Symfony (diff)

You must first sign up to be able to contribute.

Changes between Version 19 and Version 20 of Documentation/pl_PL/book/1.0/17-Extending-Symfony

Show
Ignore:
Author:
PiotrLegnica (IP: 87.105.199.91)
Timestamp:
08/25/07 17:10:30 (10 years ago)
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Documentation/pl_PL/book/1.0/17-Extending-Symfony

    v19 v20  
    11{{{ 
    22#!WikiMarkdown 
     3 
    34Rozdział 17 - Rozbudowywanie Symfony 
    45==================================== 
     6 
    57Prędzej czy później, będziesz musiał zmienić działanie symfony. Czy będziesz chciał zmienić zachowanie klasy, czy dodać nowe funkcje, ten moment na pewno nastąpi--każdy klient stawia indywidualne wymagania, których żaden framework nie da rady przewidzieć. Na szczęście ta sytuacja występuje na tyle często, że symfony udostępnia mechanizm rozbudowy klas zwany wstawkami. Możesz nawet wymienić klasy rdzenia symfony, zmieniając ustawienia fabryk. Po napisaniu rozszerzenia, możesz go spakować jako wtyczkę, aby można było użyć go w innej aplikacji, lub udostępnić innym użytkownikom symfony. 
     8 
    69Wstawki 
    710------- 
     11 
    812Pośród obecnych ograniczeń PHP, jednym z najbardziej uciążliwych jest brak możliwości dziedziczenia po więcej niż jednej klasie bazowej. Innym ograniczeniem jest brak możliwości dodawania lub nadpisywania metod już istniejącej klasy. By złagodzić te ograniczenia i uczynić framework naprawdę rozszerzalnym, symfony udostępnia klasę `sfMixer`. Nie jest ona nawiązaniem do gotowania, lecz do pojęcia wstawek w programowaniu zorientowanym obiektowo. Wstawka jest zbiorem metod lub funkcji, które mogą być dodane do klasy w celu jej rozszerzenia. 
     13 
    914###Wielokrotne dziedziczenie 
     15 
    1016Wielokrotne dziedziczenie jest zdolnością klasy do dziedziczenia po więcej niż jednej klasie bazowej. Spójrzmy na ten przykład. Wyobraź sobie klasy `Story` i `Book`, każda ma swoje właściwości i metody--tak jak pokazano na listingu 17-1. 
    1117 
    5864    $myNovel->getISBN(); 
    5965Jednym z rozwiązań mogłoby być napisanie dwóch interfejsów, które klasa `Novel` by implementowała, lecz wtedy nie byłoby   faktycznej implementacji tych metod w klasach bazowych. 
     66 
    6067###Mieszanie klas 
     68 
    6169Klasa `sfMixer` pochodzi do problemu inaczej, biorąc istniejącą klasę i rozszerzając ją a posteritori, jeśli klasa ta zawiera odpowiednie "punkty zaczepienia". Proces ten składa się z dwóch etapów: 
    6270 
    93101 
    94102###Deklarowanie klasy jako rozszerzalnej 
     103 
    95104By zadeklarować klasę jako rozszerzalną, musisz wstawić do kodu jeden lub więcej "punktów zaczepienia", które klasa `sfMixer` będzie mogła później zidentyfikować. Punkty te są wywołaniami metody `sfMixer::callMixins()`. Wiele klas symfony je posiada, w tym `sfRequest`, `sfResponse`, `sfController`, `sfUser`, czy `sfAction`. 
    96105 
    175184 
    176185###Rejestrowanie rozszerzeń 
     186 
    177187By zarejestrować rozszerzenie dla istniejącego punktu zaczepienia, wystarczy użyć metody `sfMixer::register()`. Pierwszym argumentem jest element który ma być rozszerzony, drugim funkcja PHP reprezentująca wstawkę. 
    178188 
    255265    => John sprints 500 meters 
    256266    => Nobody ever made 500 meters that fast before! 
     267 
    257268###Rozszerzanie z większą precyzją 
     269 
    258270Instrukcja `sfMixer::callMixins()` jest tak naprawdę tylko skrótem do czegoś nieco bardziej skomplikowanego. Metoda ta automatycznie przechodzi przez listę zarejestrowanych wstawek i wywołuje je pojedynczo, przekazując im rozszerzany obiekt i parametry rozszerzanej metody. W skrócie, `sfMixer::callMixins()` działa mniej więcej w sposób przedstawiony na listingu 17-11. 
    259271 
    312324Fabryki 
    313325------- 
     326 
    314327Fabryka jest definicją klasy przeznaczonej dla pewnego zadania. Rdzeń symfony używa fabryk, np. dla udostępnienia kontrolerów czy obsługi sesji. Gdy framework potrzebuje nowego obiektu żądania, przeszukuje ustawienia fabryk, by znaleźć nazwę klasy odpowiedzialnej za to zadanie. Domyślnym ustawieniem dla żądań jest `sfWebRequest`, więc symfony tworzy obiekty tej klasy, gdy musi zająć się żądaniem. Wielkim plusem stosowania ustawień fabryk, jest łatwość modyfikacji zachowania rdzenia symfony: wystarczy, że zmienisz definicję fabryki i symfony użyje twojej klasy w miejsce domyślnej. 
    315328 
    369382      request: 
    370383        class: myRequest 
     384 
    371385Pomosty do komponentów innych frameworków 
    372386----------------------------------------- 
     387 
    373388Jeżeli będziesz potrzebować funkcjonalności jakiejś klasy, ale nie będziesz chcieć kopiować jej do katalogu `lib/` symfony, prawdopodobnie umieścisz ją poza zasięgiem symfony. 
    374389W takim wypadku, będziesz musiał użyć `require` w swoim kodzie, by użyć tej klasy, chyba, że użyjesz pomostu by skorzystać z autoloadera symfony. 
    409424    ... 
    410425Dostępne pomosty są przechowywane w katalogu `$sf_symfony_lib_dir/addon/bridge/`. 
     426 
    411427Wtyczki 
    412428------- 
     429 
    413430Prawdopodobnie będziesz musiał ponownie użyć fragmentu kodu który napisałeś dla jednej z twoich aplikacji symfony. Jeżeli możesz tą funkcjonalność zmieścić w jednej klasie, wtedy nie ma problemu: Wrzuć klasę do folderu `lib/` innej aplikacji i autoloader zajmie się resztą. Jeśli jednak kod jest rozrzucony po wielu plikach, na przykład kompletnie nowy styl do generatora panelu administracyjnego lub kombinacja plików JavaScript i funkcji pomocniczych do automatyzacji twojego ulubionego efektu wizualnego, kopiowanie plików nie jest najlepszym rozwiązaniem. 
    414431 
    416433 
    417434Więc, krótko mówiąc, wtyczka jest spakowanym rozszerzeniem dla projektu symfony. Dzięki wtyczkom, będziesz mógł dzielić pomiędzy aplikacje nie tylko swój kod, ale także używać kodu wniesionego przez innych i dodawać nowe rozszerzenia do rdzenia symfony. 
     435 
    418436###Znajdowanie wtyczek do Symfony 
     437 
    419438Strona projektu symfony zawiera podstronę dedykowaną wtyczkom. Jest ona częścią wiki symfony i jest dostępna pod adresem: 
    420439 
    446465 
    447466Oprócz wiki symfony, innymi drogami do rozprowadzania wtyczek jest udostępnienie archiwów wtyczki do ściągnięcia, umieszczenia ich na kanale PEAR, lub w publicznym repozytorium kontroli wersji. 
     467 
    448468###Instalowanie wtyczki 
     469 
    449470Proces instalacji wtyczki jest różny dla każdego sposobu pakowania. Zawsze sprawdź dołączony plik `README` i/lub instrukcje instalacji na stronie wtyczki. Oprócz tego, zawsze czyść cache symfony po instalacji wtyczki. 
    450471 
    451472Wtyczki są instalowane dla całych projektów. Każda z metod opisanych w następnych sekcjach kończy się umieszczeniem plików wtyczki w katalogu `myproject/plugins/pluginName/`. 
     473 
    452474####Wtyczki PEAR 
     475 
    453476Wtyczki wymienione na wiki symfony są udostępnione jako pakiety PEAR dołączone do strony wiki. By zainstalować taki plugin, użyj zadania `plugin-install` podając pełny adres URL, tak jak pokazano na listingu 17-15. 
    454477 
    476499 
    477500Wszystkie te sposoby instalacji używają pakietów PEAR, więc termin "wtyczka PEAR" będzie używany ogólnie do określenia wtyczek zainstalowanych z wiki symfony, kanału PEAR, albo ściągniętego archiwum PEAR. 
     501 
    478502####Wtyczki spakowane 
     503 
    479504Niektóre wtyczki są zwykłymi archiwami. By je zainstalować, po prostu rozpakuj zawartość archiwum do folderu `plugins/` twojego projektu. Jeżeli wtyczka zawiera podfolder `web/`, skopiuj go albo dowiąż do katalogu `web/` projektu, tak jak pokazano na listingu 17-18. I nie zapomnij wyczyścić cache. 
    480505 
    488513 
    489514####Instalacja wtyczek z systemów kontroli wersji 
     515 
    490516Źródła wtyczek są czasem przechowywane w repozytoriach kodu dla kontroli wersji. Możesz je zainstalować poprzez wykonanie prostego checkoutu kodu do katalogu `plugins/`, ale może to być kłopotliwe, jeśli twój projekt także jest pod kontrolą wersji. 
    491517 
    504530 
    505531####Aktywacja modułu z wtyczki 
     532 
    506533Niektóre wtyczki zawierają całe moduły. Jedyną różnicą między modułami z wtyczek a klasycznymi modułami jest fakt, że moduły z wtyczek nie są przechowywane w katalogu `myproject/apps/myapp/modules/` (w celu łatwej aktualizacji). Muszą one być także aktywowane w pliku `settings.yml`, jak pokazano na listingu 17-20. 
    507534 
    518545 
    519546####Wyświetlanie listy zainstalowanych wtyczek 
     547 
    520548Jeżeli spojrzenie na katalog `plugins/` projektu mówi ci jakie wtyczki są zainstalowane, zadanie `plugin-list` powie ci nawet więcej: numer wersji oraz nazwę kanału z którego została zainstalowana wtyczka (zobacz listing 17-21). 
    521549 
    531559 
    532560####Aktualizacja i usuwanie wtyczek 
     561 
    533562By odinstalować wtyczkę PEAR, wywołaj zadanie `plugin-uninstall` z katalogu głównego projektu, tak jak pokazano na listingu 17-22. Musisz poprzedzić nazwę wtyczki nazwą kanału z którego została zainstalowana (użyj zadania `plugin-list` by się tego dowiedzieć). 
    534563 
    545574 
    546575By zaktualizować wtyczkę, użyj zadania `plugin-upgrade` (dla wtyczek PEAR) lub wywołaj `svn update` (dla wtyczek z SVN). Aktualizacja wtyczek rozprowadzanych jako archiwa jest nieco trudniejsza. 
     576 
    547577###Anatomia wtyczki 
     578 
    548579Wtyczki są pisane w PHP. Jeżeli rozumiesz jak zorganizowane są aplikacje, zrozumiesz także strukturę wtyczki. 
     580 
    549581####Struktura plików wtyczki 
     582 
    550583Katalog wtyczki jest zorganizowany mniej więcej tak, jak katalog projektu. Pliki wtyczki muszą znajdować się we właściwych folderach, by mogły być znalezione przez symfony. Przyjrzyj się strukturze plików wtyczki opisanej na listingu 17-23. 
    551584 
    589622 
    590623####Możliwości wtyczek 
     624 
    591625Wtyczki mogą zawierać wiele rzeczy. Ich zawartość jest automatycznie brana pod uwagę przez aplikację podczas działania i podczas wywoływania zadań z poziomu linii komend. Jednak by wtyczki działały jak należy, musisz uszanować kilka konwencji: 
    592626 
    613647 
    614648####Ręczne ustawianie wtyczki 
     649 
    615650Są pewne elementy których zadanie `plugin-install` nie może obsłużyć, i które wymagają ręcznego ustawiania podczas instalacji: 
    616651*  Dodatkowa konfiguracja aplikacji może być używana w kodzie wtyczki (np. używając `sfConfig::get('app_myconfig_foo')`), ale nie możesz umieścić domyślnych wartości w pliku `app.yml` zlokalizowanym w katalogu `config/` wtyczki. By obsłużyć domyślne wartości, użyj drugiego argumentu `sfConfig::get()`. Ustawienia wciąż mogą być nadpisane przez aplikację (zobacz listing 17-25). 
    620655 
    621656Ogólnie rzecz biorąc, cała konfiguracja mająca wylądować w plikach konfiguracyjnych aplikacji musi być dodana ręcznie. Wtyczki wymagające ręcznej instalacji powinny zawierać plik `README` szczegółowo opisujący proces instalacji. 
     657 
    622658####Personalizowanie wtyczki dla aplikacji 
     659 
    623660Kiedy chcesz spersonalizować wtyczkę, nigdy nie zmieniaj kodu znajdującego się w katalogu `plugins/`. Jeśli to zrobisz, stracisz swoje modyfikacje po aktualizacji wtyczki. Do potrzeb personalizacji wtyczki udostępniają konfigurację i wspierają nadpisywanie. 
    624661 
    670707 
    671708###Jak napisać wtyczkę 
     709 
    672710Tylko wtyczki pakowane jako pakiety PEAR mogą być instalowane poprzez zadanie `plugin-install`. Pamiętaj, że taka wtyczka może być rozprowadzana poprzez wiki symfony, kanał PEAR, lub zwykły download. Więc jeżeli chcesz być autorem wtyczki, lepiej jest opublikować ją jako pakiet PEAR niż jako zwykłe archiwum. Dodatkowo, wtyczki spakowane jako pakiety PEAR są łatwiejsze w aktualizacji, mogą deklarować zależności i automatycznie umieszczać assety w katalogu `web/`. 
     711 
    673712####Organizacja plików 
     713 
    674714Przypuśćmy, że zaimplementowałeś nową funkcję i chcesz spakować ją jako wtyczkę. Pierwszym krokiem jest logiczna organizacja plików, by mechanizmy ładowania symfony mogły je znaleźć. W tym celu musisz trzymać się struktury pokazanej na listingu 17-23. Listing 17-27 pokazuje przykładową strukturę plików wtyczki `sfSamplePlugin`. 
    675715 
    714754 
    715755####Tworzenie pliku package.xml 
     756 
    716757Następnym krokiem tworzenia wtyczki jest stworzenie pliku `package.xml` w katalogu głównym wtyczki. Plik ten podąża za składnią PEAR. Przyjrzyj się typowemu plikowi `package.xml` wtyczki symfony na listingu 17-28. 
    717758 
    813854 
    814855Interesującymi częściami są tagi `<contents>` i `<dependencies>`, opisane niżej. Co do reszty tagów, nie ma w nich nic specyficznego dla symfony, więc możesz odnieść się do dokumentacji PEAR (<http://pear.php.net/manual/en>) po więcej informacji nt. formatu `package.xml`. 
     856 
    815857####Zawartość 
     858 
    816859Tag `<contents>` jest miejscem w którym opisujesz strukturę plików wtyczki. Dzięki temu PEAR będzie wiedzieć co skopiować gdzie. Opisz strukturę plików używając tagów `<dir>` i `<file>`. Wszystkie tagi `<file>` muszą mieć atrybut `role="data"`. Część `<contents>` listingu 17-28 opisuje strukturę plików z listingu 17-27. 
    817860 
    820863 
    821864####Zależności wtyczek 
     865 
    822866Wtyczki są zaprojektowane by działać z odpowiednimi wersjami PHP, PEAR, symfony, pakietów PEAR lub innych wtyczek. 
    823867Zadeklarowanie tych zależności w tagu `<dependencies>` pozwoli PEAR-owi określić, czy wymagane pakiety są już zainstalowane i w razie potrzeby wygenerować wyjątek. 
    826870 
    827871Zalecane jest także zadeklarowanie maksymalnej wersji symfony dla każdej wtyczki. Spowoduje to wygenerowanie błędu gdy użytkownik będzie chciał użyć wtyczki z bardziej zaawansowaną wersją frameworka, i zobliguje autora wtyczki do sprawdzenia, czy działa ona z daną wersją przed wydaniem kolejnej wersji. Lepiej dostać ostrzeżenie i ściągnąć aktualizację niż mieć wtyczkę, która po cichu przestanie działać. 
     872 
    828873####Budowanie wtyczki 
     874 
    829875Komponent PEAR posiada komendę (`pear package`) która tworzy archiwum .tgz pakietu, jeśli zostanie ona wywołana z katalogu zawierającego `package.xml`, jak pokazano na listingu 17-29. 
    830876 
    883929 
    884930Przetestuj zachowanie wtyczki w swojej aplikacji. Jeżeli działa dobrze, jesteś gotowy do umieszczenia jej w innych projektach--lub udostępnienia jej społeczności symfony. 
     931 
    885932####Zamieszczanie własnej wtyczki na stronie Symfony 
     933 
    886934Wtyczka symfony zyskuje większą popularność, gdy jest rozpowszechniana poprzez stronę `symfony-project.com`. Twoje wtyczki także mogą być rozpowszechniane tą drogą, jeżeli wykonasz następujące instrukcje: 
    8879351.  Upewnij się, że plik `README` opisuje instalację i użycie twojej wtyczki, i że plik `LICENSE` zawiera informacje o użytej licencji. Sformatuj swój plik `README` używając składni formatowania Wiki (<http://www.symfony-project.com/trac/wiki/WikiFormatting>). 
    896944 
    897945####Nazewnictwo 
     946 
    898947By utrzymać porządek w folderze `plugins/`, upewnij się, że nazwy wtyczek są napisane `wielbłądzimStylem` i kończą się na `Plugin` (na przykład, `shoppingCartPlugin`, `feedPlugin`, itp.). Przed nazwaniem swojej wtyczki sprawdź czy nie istnieje już wtyczka o takiej samej nazwie. 
    899948 
    902951 
    903952Wtyczki powinny zawsze zawierać plik `LICENSE` zawierający warunki użycia i wybraną licencję. Powinieneś także dodać plik `README` do wyjaśnienia zmian wersji, przeznaczenia wtyczki, jej działania, instalacji i konfiguracji, itp. 
     953 
    904954Podsumowanie 
    905955------------ 
     956 
    906957Klasy symfony zawierają punkty zaczepienia `sfMixer` które dają możliwość modyfikacji ich z poziomu aplikacji. Mechanizm wstawek pozwala na wielokrotne dziedziczenie i nadpisywanie klas podczas działania, nawet jeśli ograniczenia PHP tego zabraniają. Możesz więc łatwo rozszerzyć możliwości symfony, nawet jeśli musisz zmodyfikować klasy rdzenia--po to powstała konfiguracja fabryk. 
    907958