Struktura katalogów

Zanim przejdziemy do utworzenia pierwszego kontrolera, zapoznaj się ze strukturą katalogów i elementami jakie posiada Kohana.

Całość dzieli się na 3 katalogi:

  • system – tu znajduje się „serce” naszego frameworka, w tym główny rdzeń (core) oraz inne elementy, których krótki opis znajduje się poniżej;
  • modules – zawiera kod (biblioteki, modele, widoki itp.), który jest na tyle uniwersalny, że może być wykorzystywany w innych projektach (np. obsługa użytkowników);
  • application – ten katalog będzie nas interesował najbardziej. To w nim przechowywane są wszystkie pliki związane z naszą aplikacją.
Rys. 2.1. Struktura katalogów

Nasze skrypty uruchamiane są poprzez plik index.php. To on ładuje podstawowe klasy Kohany, które później decydują który z elementów naszej aplikacji ma być obsłużony.

Elementy Kohany

Jak zapewne zauważyłeś, we wszystkich 3 katalogach jest podobna struktura podkatalogów:

  • config – jak sama nazwa wskazuje zawiera pliki z konfiguracją aplikacji, bibliotek czy też poszczególnych modułów. Więcej informacji na temat konfiguracji znajdziesz w następnym artykule;
  • helpers – zawiera klasy podobne do bibliotek (libraries) z tym wyjątkiem, że posiadają metody statyczne, przez co nie potrzebna jest instancja klasy, żeby użyć którejś z jej funkcji;
  • hooks – czasem istnieje potrzeba uruchomienia kawałka kodu poza ramami działania kontrolera (np. przed jego wywołaniem lub w momencie wysłania nagłówków). Do tego właśnie służą “haki”;
  • i18n (skrót od internationalization) – katalog ten zawiera pliki językowe z komunikatami i tekstami, które chcemy aby były przetłumaczone na naszej stronie. Poza zdefiniowanymi standardowo można utworzyć własne;
  • libraries – katalog z naszymi bibliotekami wykorzystywanymi w aplikacji;
  • vendor – znalazłeś w internecie jakąś bibliotekę, której chciałbyś użyć w Kohanie? To miejsce jest właśnie dla niej. W tym katalogu przechowywane są klasy zewnętrznych bibliotek, zaadoptowane do współpracy z naszym frameworkiem;
  • controllers, models, views – elementy te pokrótce były opisane wcześniej, więc nie ma sensu się nad nimi rozwodzić. W następnych wpisach zajmiemy się dokładniej ich tworzeniem i zastosowaniem w aplikacji.

Kaskadowy system plików

Charakterystyczną rzeczą, wartą uwagi w Kohanie jest kaskadowy system plików. Takie rozwiązanie pozwala na nadpisanie plików bez konieczności ich modyfikacji czy usuwania.  Jeśli chcemy otworzyć jakiś plik będzie on przeszukiwany w katalogach w kolejności application -> modules -> system. Jeśli plik nie znajdzie się w żadnym z nich, to zostanie wyświetlony komunikat błędu (w przypadku braku kontrolera błąd 404). Podkatalogi w modules są przeglądane w kolejności ich dodania w pliku konfiguracyjnym config.php (o konfiguracji powiemy w następnym artykule). Spójrz na poniższy rysunek.

Rys. 2.2. Kaskadowy system plików (autor Geert De Deckere)

W katalogu system/views mamy widok layout.php, który posiada szkielet strony. Ale my chcemy mieć własny szkielet z własnym wyglądem. Dlatego też tworzymy plik o tej samej nazwie w katalogu naszej aplikacji (application/views). Dzięki temu Kohana otrzymując polecenie odnalezienia widoku, szuka go najpierw w naszym katalogu. W tym przypadku znalazł go od razu, więc pomija pozostałe lokalizacje. Dla widoku products.php, który znajduje się aż w trzech miejscach (module a, module b oraz system), wygrywa katalog module a, ponieważ był najwyżej w hierarchi.

Rozwiązanie to jest bardzo użyteczne w przypadku konfiguracji. W zasadzie nie powinieneś nic zmieniać w katalogu system, ponieważ w przypadku aktualizacji Kohany stracisz wszystkie zmiany, a po pewnym czasie raczej nie będziesz pamiętać co i gdzie zmieniłeś.  Zatem jeśli brakuje jakiegoś pliku, który istnieje w katalogu system/config, bądź w którymś z modułów, a który chcesz zmodyfikować, to skopiuj go do application/config i tam dopiero modyfikuj.

Standardy nazewnictwa

Aby Kohana wiedziała gdzie znaleźć elementy naszej aplikacji musimy zachować pewne standardy.

  • Kontrolery (controllers):

    • nazwa pliku musi być zapisana małymi literami, np. artykuly.php;
    • nazwa kontrolera musi się pokrywać z nazwą pliku , dodatkowo kończy się sufiksem _Controller (np. Artykuly_Controller). Pierwsze litery wyrazów są duże, pozostałe małe;
    • musi dziedziczyć po klasie Controller bądź jednym z jego potomków;
    • standardowo wywoływana jest funkcja index (jeśli nie podano inaczej).
  • Pomocniki (helpers):

    • nazwę pliku i klasy zapisujemy małymi literami.  Nazwa pliku pokrywa się z nazwą klasy (z wyjątkiem sufiksu _Core);
    • do nazw nowych klas dodajemy sufiks _Core, np. html_Core, tak aby w przyszłości możliwe było rozszerzenie funkcjonalności klasy.
  • Biblioteki (libraries):

    • nazwa pliku podobnie jak w przypadku pomocników pokrywa się z nazwą klasy (z wyjątkiem sufiksu _Core), ale musi zachować takie same wielkości liter jak nazwa klasy;
    • nazwa klasy zaczyna się od wielkiej litery, wielkość pozostałych liter zależy od programisty;
    • w przypadku nowych klas postępujemy analogicznie jak w pomocnikach.
  • Modele (models):

    • nazwy plików składają się z małych liter i mają taką samą nazwę jak klasa (bez sufiksu _Model);
    • nazwa modelu musi się pokrywać z nazwą pliku, dodatkowo kończy się sufiksem _Model (np. User_Model). Pierwsze litery wyrazów są duże, pozostałe małe;
    • nazwa modelu powinna być zapisana w liczbie pojedynczej (ważne w przypadku angielskich nazw i użycia ORM).
  • Widoki (views):

    • nazwy plików w tym przypadku mogą być dowolne, wielkość liter nie ma znaczenia, byleby przy wywołaniu widoku ją zachować. Musi być jedynie zakończona rozszerzeniem .php.