Development

Documentation/pl_PL/book/1.0/05-Configuring-Symfony

You must first sign up to be able to contribute.

Oryginalny tekst: http://www.symfony-project.com/book/trunk/05-Configuring-Symfony [EN]

WERSJA ROBOCZA

Rozdział 5 - Konfigurowanie symfony

Aby framework symfony był prosty i łatwy w użyciu, utworzono kilka konwencji, które powinny spełnić najbardziej podstawowe wymagania dla tego typu aplikacji bez potrzeby żadnych modyfikacji. Jednak użycie prostych i potężnych plików konfiguracyjnych pozwala na dostosowanie prawie wszystkich aspektów współpracy frameworka z Twoją aplikacją. Użycie plików konfiguracyjnych pozwala także na dodanie specyficznych parametrów dla aplikacji.

Ten rozdział wyjaśnia jak działa system konfiguracji:

  • Konfiguracja symfony jest trzymana w plikach napisanych w języku YAML, jednak zawsze możesz wybrać inny format.
  • Pliki konfiguracyjne znajdują się na poziomie projektu, aplikacji i modułu w hierarchii katalogów projektu.
  • Możesz stworzyć wiele zbiorów ustawień; w symfony zbiór zestawień jest nazywany środowiskiem.
  • Wartości zdefiniowane w plikach konfiguracyjnych są dostępne w kodzie PHP aplikacji.
  • Dodatkowo, symfony pozwala na użycie kodu PHP w plikach YAML oraz udostępnia inne sposoby, by pliki konfiguracyjne były jeszcze bardziej elastyczne.

System konfiguracji

Niezależnie od celu, większość aplikacji sieciowych posiada wspólny zbiór funkcjonalności. Na przykład, niektóre sekcje aplikacji mogą być dostępne tylko dla określonego podzbioru użytkowników, strony są otaczane layoutem, formularz może być wypełniony danymi wprowadzonymi przez użytkownika po nieudanej walidacji. Framework zapewnia obsługę tych funkcjonalności, a developer może dostosować je do własnych potrzeb używając plików konfiguracyjnych. Ten sposób pisania aplikacji pozwala na zaoszczędzenie dużych ilości czasu, ponieważ wiele zmian w aplikacji nie wymaga napisania ani jednej linijki kodu, nawet, jeśli za zmianami kryje się duża ilość kodu. Jest to także rozwiązanie dużo bardziej skuteczne, ponieważ zapewnia, że zmiany mogą być dokonywane w pojedynczym i łatwym do odnalezienia miejscu.

Jednak takie rozwiązanie ma dwa poważne minusy:

  • programiści mogą skończyć na pisaniu niekończących się, skomplikowanych plików XML.
  • w architekturze PHP, każde żądanie znacząco się wydłuży.

Biorąc te minusy pod uwagę, symfony używa plików konfiguracyjnych tylko tam, gdzie są one najbardziej porządane i przydatne. Prawdę mówiąc, celem systemu konfiguracji w symfony jest bycie:

  • Potężnym: Prawie każdy aspekt aplikacji, który może być zarządzany przy użyciu plików konfiguracyjnych, jest przez nie zarządzany.
  • Prostym: Wiele aspektów konfiguracji nie jest widoczna w normalnej aplikacji, ponieważ żadko zachodzi potrzeba ich zmiany.
  • Łatwym: Pliki konfiguracyjne są łatwe w odczycie, modyfikacji i tworzeniu przez programistę.
  • Konfigurowalnym: Domyślnym językiem plików konfiguracyjnych jest YAML, lecz można je tworzyć także jako pliki INI, XML, lub jakimkolwiek innym formacie preferowanym przez programistę.
  • Szybkim: Pliki konfiguracyjne nigdy nie jest przetwarzane pzez aplikację, lecz przez system konfiguracji, który kompiluje je do szybkiego w przetwarzaniu kodu PHP.

Składnia języka YAML i konwencje symfony

Domyślnym językiem plików konfiguracyjnych w symfony jest YAML, zamiast bardziej tradycyjnych formatów INI czy XML. YAML przedstawia strukturę za pomocą wcięć i szybki w tworzeniu. Jego zalety i proste zasady zostały już opisane w [link]Rozdziale 1[/link]. Jednakże, musisz pamiętać o kilku zasadach podczas tworzenia plików YAML. Ta sekcja wprowadza najbardziej znaczące zasady. Pełny opis języka YAML można znaleźć na stronie http://www.yaml.org.

Po pierwsze, nie wolno używać tabulacji w plikach YAML - używaj zamiast nich spacji. Parsery języka YAML nie dają sobie rady z tabulacjami, więc twórz wcięcia za pomocą spacji (symfony przyjmuje konwencję dwóch spacji jako wcięcia), jak pokazano na Listingu 5-1.

Listing 5-1 - W plikach YAML spacje są zabronione

# Nigdy nie używaj tabulacji
all:
-> mail:
-> -> webmaster:  webmaster@example.com

# Zamiast tego używaj spacji
all:
  mail:
    webmaster: webmaster@example.com

Jeśli parametrem jest ciąg znaków rozpoczynający się lub kończący spacjami, otocz go apostrofami. To samo dotyczy ciągów znaków zawierających znaki specjalne, jak pokazano na Listingu 5-2.

Listing 5-2 - Niestandardowe ciągi znaków powinny być otoczone apostrofami

error1: This field is compulsory
error2: '  This field is compulsory  '
error3: 'Don''t leave this field blank'   # Apostrofy w tekście należy wpisać dwukrotnie

Możesz tworzyć długie ciągi znaków w wielu liniach, jak również wieloliniowe ciągi, używając specjalnych nagłówków (> i |) wraz z dodatkowym wcięciem. Listing 5-3 demonstruje tą konwencję.

Listing 5-3 - Tworzenie długich i wieloliniowych ciągów znaków

# Styl zawinięty, poprzedzany znakiem >
# Każdy znak nowej linii jest zamieniany na spację
# Dzięki temu plik YAML jest bardziej czytelny
accomplishment: >
  Mark set a major league
  home run record in 1998.

# Styl literałowy, poprzedzany znakiem |
# Wszystkie znaki nowej linii mają znaczenie
# Wcięcia nie są uwzględnione w ciągu wyjściowym
stats: |
  65 Home Runs
  0.278 Batting Average

By zdefiniować wartość jako tablicę, otocz jej elementy nawiasami kwadratowymi ub użyj rozszerzonej składni wykorzystującej myślniki, jak pokazano na Listingu 5-4.

Listing 5-4 - Składnia tablic w języku YAML

# Skrócona składnia tablic
players: [ Mark McGwire, Sammy Sosa, Ken Griffey ]

# Rozszerzona składnia tablic
players:
  - Mark McGwire
  - Sammy Sosa
  - Ken Griffey

By zdefiniować wartość jako tablicę asocjacyjną, otocz elementy nawiasami klamrowymi i zawsze dodawaj spacje pomiędzy kluczem i wartością w parze {klucz: wartość}. Możesz także użyć rozszerzonej składni dodając wcięcie i znak nowej linii dla każdego nowe klucza, jak pokazano na Listingu 5-5.

Listing 5-5 - Składnia tablic asocjacyjnych w języku YAML

# Niepoprawna składnia - brak spacji po dwukropkach
mail: {webmaster:webmaster@example.com,contact:contact@example.com}

# Poprawna skrócona składnia tablic asocjacyjnych
mail: { webmaster: webmaster@example.com, contact: contact@example.com }

# Rozszerzona składnia tablic asocjacyjnych
mail:
  webmaster: webmaster@example.com
  contact:   contact@example.com

By nadać wartość logiczną, użyj 1, on lub true dla wartości pozytywnej i off, 0 lub false dla negatywnej. Listing 5-6 pokazuje możliwe wartości logiczne.

Listing 5-6 - Wartości logiczne w języku YAML

true_values:   [ on, 1, true ]
false_values:  [ off, 0, false ]

Nie wahaj się dodawać komentarzy (zaczynających się znakiem #) i dodatkowych spacji by uczynić pliki YAML bardziej czytelnymi, jak pokazano na Listingu 5-7.

Listing 5-7 - Składnia komentarzy i wyrównywanie wartości

# To jest komentarz
mail:
  webmaster: webmaster@example.com
  contact:   contact@example.com
  admin:     admin@example.com   # dodatkowe spacje są dozwolone do wyrównywania wartości

W niektórych plikach konfiguracyjnych symfony, zauważysz linie które zaczynają się znakiem # (i, jako takie są ignorowane przez parsery YAMLa) lecz wyglądają jak normalne linie z ustawieniami. To konwencja przyjęta w symfony: domyślna konfiguracja, dziedziczona po innym pliku YAML zdefiniowanym w jądrze symfony, jest powtarzana w za komentowanych liniach konfiguracji Twojej aplikacji, w celach informacyjnych. Jeśli chcesz zmienić wartość takiego parametry, musisz najpierw od komentować linię, jak pokazano na Listingu 5-8.

Listing 5-8 - Domyślna konfiguracja jest za komentowana

# Cachowanie jest domyślnie wyłączone
settings:
# cache: off

# Jeśli chcesz zmienić to ustawienie, od komentuj najpierw linię
settings:
  cache: on

Symfony grupuje czasem definicję parametrów w kategorie. Wszystkie ustawienia danej kategorii są przedstawiane z wcięciem pod nagłówkiem kategorii. Strukturyzowanie długich list par {klucz: wartość} przez grupowanie ich w kategorie poprawia czytelność konfiguracji. Nagłówki kategorii zaczynają się kropką (.). Listing 5-9 przedstawia przykład kategorii.

Listing 5-9 - Nagłówki kategorii wyglądają jak klucze, lecz zaczynają się kropką

all:
  .glowne:
    tax:        19.6

  mail:
    webmaster:  webmaster@example.com

W tym przykładzie, mail jest kluczem a glowne tylko nagłówkiem kategorii. Wszystko działa tak, jakby nagłówek kategorii nie istniał, jak pokazano na Listingu 5-10. Parametr tax jest tak naprawdę bezpośrednim dzieckiem klucza all.

Listing 5-10 - Nagłówki kategorii mają na celu tylko poprawę czytelności i są tak naprawdę ignorowane

all:
  tax:          19.6

  mail:
    webmaster:  webmaster@example.com

**SIDEBAR** A jeśli nie spodobał Ci się YAML YAML jest tylko interfejsem pozwalającym definiować wartości używane w kodzie PHP, więc konfiguracja zdefiniowana w plikach YAML zostanie przetworzona do kodu PHP. Po użyciu swojej aplikacji, możesz obejrzeć zcacheowaną wersję konfiguracji (np. w pliku cache/myapp/dev/config). Znajdziesz tam pliki PHP odpowiadające plikom konfiguracyjnym YAML. O cacheowaniu konfiguracji dowiesz się więcej w dalszej części rozdziału. Jeśli nie chcesz używać plików YAML, możesz z nich zrezygnować i wykorzystać inny format (XML, INI itd.) lub ręcznie utworzyć pliki PHP. W książce napotkasz na alternatywne sposoby definiowania konfiguracji bez użycia YAMLa, a nawet nauczysz się podmieniać klasy do obsługi konfiguracji w symfony na własne (w rozdziale 19). Jeśli będziesz z nich korzystał w mądry sposób, będziesz mógł ominąć pliki konfiguracyjne bądź też utworzyć swój własny format konfiguracji.

=== Pomocy, plik YAML zabił moją aplikację!

Pliki YAML są przetwarzane do tablic w PHP, a następnie ich wartości są używane w różnych częściach aplikacji do zmiany zachowania widoku, kontrolera czy modelu. W wielu przypadkach, gdy wystąpi problem w pliku YAML, nie zostanie on wykryty zanim wartość nie będzie potrzebna. Co więcej, błąd lub wyjątek, który zostanie wyrzucony, nie powie nam wprost, że jest związany z plikiem konfiguracyjnym YAML.

Jeśli aplikacja nagle przestanie działać po zmianach w pliku konfiguracyjnym, powinieneś sprawdzić czy nie popełniłeś jednego z często popełnianych przez nieuważnych programistów błędu:

  • Zapomniałeś o spacji pomiędzy kluczem i wartością:

key1:value1 # Brak spacji po dwukropku

  • Klucze w sekwencji nie posiadają jednakowych wcięć:

all:

key1: value1

key2: value2 # Poziom wcięcia nie jest taki sam

key3: value3

  • Użyłeś zarezerwowanego znaku języka YAML w kluczu lub wartości bez użycia apostrofów:

message: tell him: go way # znaki :, [, ], { and } są zarezerwowane w YAML'u message: 'tell him: go way' # Poprawna składnia

  • Robisz zmiany w zakomentowanej linii:

# key: value # Ustawienie nigdy nie będzie brane pod uwagę przez znak # na początku

  • Ustawiasz dwa razy wartość dla tego samego klucza na jednym poziomie:

key1: value1 key2: value2 key1: value3 # klucz key1 jest ustawiany dwa razy, pod uwagę zostanie wzięta ostatnia ustawiona wartość

  • Wydaje Ci się, że ustawienie przyjmie specjalny typ, podczas gdy jest zawsze ciągiem znaków, dopóty dopóki go nie skonwertujesz:

income: 12,345 # Dopóki nie dokonasz konwersji, wartość pozostanie ciągiem znaków.

Przegląd plików konfiguracyjnych


Konfiguracja jest rozdzielona na podzielone tematycznie pliki. Zawierają one definicję parametrów lub ustawień. Niektóre z tych parametrów mogą być nadpisane na różnych poziomach (projektu, aplikacji czy modułu); niektóre są specyficzne dla określonego poziomu. Następne rozdziały będą skupiać się na plikach konfiguracych powiązanych z głównym tematem rozdziału, natomiast w rozdziale 19 zostanie omówiona zaawansowana konfiguracja.

=== Konfiguracja projektu

Kilka plików konfiguracyjnych projektu jest utworzonych domyślnie. Oto pliki, które można znaleźć katalogu myproject/conifg/:

  • config.php: Jest to jeden z pierwszych plików, które są wykonywane po przyjęciu jakiekolwiek żądania. Zawiera on ścieżkę do plików frameworku, którą możesz zmienić by użyć innej instalacji frameworka. Jeśli dodasz jakieś definicje stałych na końcu tego pliku, stałe te będą dostępne w każdej aplikacji tego projektu. Rozdział 19 opisuje ten plik dokładniej.
  • databases.yml: W tym pliku definiowany jest sposób dostępu do bazy danych (host, login, hasło, nazwa bazy itd.). Rozdział 8 zawiera więcej informacji o tym pliku. Można go nadpisać na poziomie aplikacji.
  • properties.ini: Ten plik przechowuje kilka parametrów używanych przez narzędzia dostępne z linii komend, m. in. nazwę projektu i ustawienia połączeń z odległymi serwerami. W rozdziale 16 znajduje się szerszy opis możliwości użycia tego pliku.
  • rsync_exclude.txt: Ten plik określa które katalogi powinny być wykluczone z synchronizacji pomiędzy serwerami. Jest omówiony w rozdziale 16.
  • schema.yml i propel.ini: Są to pliki konfiguracyjne dostępu do danych używane przez Propel (warstwę ORM symfony). Dzięki nim biblioteki Propela mogą współdziałać z klasami symfony i danymi Twojego projektu. Plik schema.yml zawiera reprezentację relacyjnego modelu danych projektu. Plik propel.ini jest generowany automatycznie, więc najprawdopodobniej nie będziesz musiał w nim niczego zmieniać. Jeśli nie używasz Propela, te pliku są niepotrzebne. Z rozdziału 8 dowiesz się więcej na temat ich użycia.

Te pliki są najczęściej używane przez zewnętrzne komponenty lub przez programy konsolowe, lub muszą być przetworzone jeszcze zanim jakikolwiek parser YAML'a zostanie załadowany. Dlatego niektóre z nich nie używają formatu YAML.

=== Konfiguracja aplikacji

==== Konfiguracja Front Controllera

==== Główna konfiguracja aplikacji

==== Konfiguracja internacjonalizacji

==== Dodatkowa konfiguracja aplikacji

=== Konfiguracja modułu

Środowisko


=== Czym jest środowisko?

=== Kaskada konfiguracji

Cache konfiguracji


Dostęp do konfiguracji z kodu


=== Klasa sfConfig

=== Niestandardowe ustawienia aplikacji i plik app.yml

Wskazówki jak lepiej wykorzystać pliki konfiguracyjne


=== Używanie stałych w plikach YAML

=== Używanie skryptowalnej konfiguracji

=== Przeglądanie Twojego własnego pliku YAML

Podsumowanie