Konwencje nazw CakePHP

Konwencja to ogólnie przyjęte nazwy, które należy stosować. Twórcy frameworka CakePHP określili się jako wielcy fani stosowania konwencji, dlatego warto poświęcić kilka chwil na zrozumienie konwencji nazw przyjętych w tym narzędziu, co pozwoli uniknięcie wielu pułapek i problemów podczas tworzenia aplikacji w przyszłości. Twórcy CakePHP są określają się jako „wielcy fani konwencji, która w przypadku tego frameworka jest ważniejsza niż konfiguracja. Co daje takie podejście? Choć nauczenie się zasad nazewnictwa może zająć trochę czasu, to w praktyce umożliwia pisanie aplikacji nawet bez napisania jednej linii kodu PHP! Poprzez zachowanie konwencji, można uzyskać funkcjonalność automatycznego generowania plików konfiguracyjnych.

Projektanci narzędzia CakePHP założyli, że podczas programowania aplikacji programista będzie wykorzystywał w język angielski. Angielskie nazwy dotyczą tabel w bazach danych, modeli, kontrolerów oraz widoków. Co więcej – w zależności od elementu, wykorzystuje się nazwę w liczbie pojedynczej, jak i mnogiej. Framework rozróżnia także liczbę pojedynczą oraz mnogą nazw, zaś w języku angielskim liczbę mnogą tworzy się dodając końcówkę -s lub -es, a dzięki temu, CakePHP poprawnie zinterpretuje takie nazewnictwo. Choć niektórzy upierają się, że stosowanie polskich nazw jest możliwe, przy większych projektach może to powodować kłopoty i należy się tego wystrzegać.

Nazwy Kontrolerów

Nazwa klasy Kontrolera musi być podana w liczbie mnogiej, w formacie CamelCased i kończyć się słowem Controller. UsersController oraz ArticleCategoriesController to przykłądy konwencji nazw kontrolera.

Nazwy plików kontrolerów muszą mieć taką samą nazwę jak kontroler z rozszerzeniem .php. Na przykład kontroler UsersController, musi być zapisany jako UsersController.php, PostsConttroller – PostsController.php, natomiast GroupsController – GroupsController.php.

Publiczne metody w kontrolerze, często nazywane ‘akcjami’, są dostępne z przeglądarki. Na przykład /users/view mapuje do metody view() w kontrolerze UsersController. Metody typu protected lub private nie są dostępne w routingu.

Uwagi dotyczące adresów URL dla nazw kontrolerów

Jak już zauważyłeś, kontrolery pojedynczych wyrazów mapują prostą ścieżkę do małych liter w adresie URL. Na przykład, UsersController (określony w pliku o nazwie UsersController.php) będzie dostępna pod adresem http://example.com/users.

Choć można nazywać kontrolery dowolnie, konwencja dotycząca nazw w adresie URLs z małymi literami odbywa się za pomocą klasy DashedRoute. W związku z tym odwołanie /article-categories/view-all jest prawidową formą dostępu do akcji ArticleCategoriesController::viewAll().

Gdy utworzysz odnośnik przy użyciu this->Html->link(), możesz zastosować następującą konwencję w tablicy url:

$this->Html->link('link-title', [
    'prefix' => 'MyPrefix' // CamelCased
    'plugin' => 'MyPlugin', // CamelCased
    'controller' => 'ControllerName', // CamelCased
    'action' => 'actionName' // camelBacked
]

Aby uzyskać więcej informacji dotyczących parametrów URLi w CakePHP, zobacz Łączenie tras routingu.

Konwencje nazw plików i nazw klas

Generalnie nazwy plików są takie same jak nawy klas, co jest zgodne ze standardami PSR-0 lub PSR-4. Poniżej podano kilka przykłądów nazw klas i nazw plików, w których zostały zapisane:

  • Klasa kontrolera LatestArticlesController zapisana wpliku o nazwie LatestArticlesController.php
  • Klasa komponentu MyHandyComponent zapisana wpliku o nazwie MyHandyComponent.php
  • Klasa tabeli OptionValuesTable zapisana wpliku o nazwie OptionValuesTable.php.
  • Klasa encji OptionValue zapisana wpliku o nazwie OptionValue.php.
  • Klasa Behavior EspeciallyFunkableBehavior zapisana wpliku o nazwie named EspeciallyFunkableBehavior.php
  • Klasa widoku SuperSimpleView zapisana wpliku o nazwie SuperSimpleView.php
  • Klasa helpera BestEverHelper zapisana wpliku o nazwie BestEverHelper.php

Każdy plik znajdowałby się w odpowiednim folderze/przestrzeni nazw w folderze aplikacji.

Konwencja nazw modeli i tabel w bazie danych

Nazwa modelu zaczyna się od wielkiej litery i jest pisana w liczbie mnogiej. Nazwę modelu tworzy się na podstawie nazwy tabeli (pisanej w liczbie mnogiej, z małej litery).

Nazwy tabel wykorzystywanych w modelach CakePHP muszą być podawane w liczbie mnogiej i jeśli są dłuższe, z podkreśleniem. Podstawowymi tabelami dla powyższych będzie users, article_categories i odpowiednio user_favorite_pages.

Konwencje dotyczą sów angielskich jako nazw pól w tabelach. Jeżeli użyjesz słów w innych językach, CakePHP może niepoprawnie je rozpoznać w procesie tzw. przekształcenia (inflections) - (z liczby pojedynczej do mnogiej i odwrotnie). Jeśli więc potrzebujesz wykorzystać zasady włąsnego języka (nie polecam), użyj klasy Cake\Utility\Inflector, by zdefiniować własne zasady przekształceń. Ta klasa pozwala również sprawdzić, czy CakePHP rozumie niestandardową składnię liczb i liczby mnogiej. Zobacz dokumentację Inflector aby dowiedzieć się więcej.

Nazwy pól z dwoma lub większą ilością słów muszą być podkreślone: first_name.

Klucz obcy w relacjach hasMany czy belongsTo/hasOne jest rozpoznawany domyślnie jako nazwa w liczbie pojedynczej z powiązanej tebali oraz zakończeniem _id. Tak więc jeśli mamy Users hasMany Articles (użytkownik posiada wiele artykułów), tabela articles odnosi się do tabeli users poprzez pole klucza obcego user_id. Dla tabeli jak article_categories którego nazwa skłąda się z wielu słóww, klucz obcy będzie article_category_id.

Połączenie tabel, używane przy relacjach pomiędzy modelami typu BelongsToMany, powinny być nazywane jak modele tabel, które będą łączone, ułożone w kolejności alfabetycznej (articles_tags rather than tags_articles).

Dodatkowo do użycia klucza auto-increment jako klucza głównego, możesz także użyć kolumny UUID. CakePHP utworzy wówczas unikatowy, 36 znakowy UUID (Cake\Utility\Text::uuid()) ilekroć będziesz zapisywał rekord za pomocą metody Table::save().

Konwencje nazw widoków

Pliki szablonów widoków są nazywane od funkcji (akcji) w kontrolerze. Np. funkcja display w kontrolerze wywoła widok dicplay, zaś funkcja viewAll() w klasie kontrolera ArticlesController będzie poszukiwać pliku szablonu src/Template/Articles/view_all.ctp.

Podstawowym wzrorem jest src/Template/Controller/underscored_function_name.ctp.

Dzięki nazewnictwu zgodnemu z konwencją CakePHP, uzyskuje się bezproblemową funkcjonalność i to bez użycia jakiejkolwiek konfiguracji. Oto finalny przykład, który zawiera konwencje nazw zgodnych w CakePHP:

  • Tabala w bazie danych: “articles”
  • Klasa tabeli: ArticlesTable, znajdue się w src/Model/Table/ArticlesTable.php
  • Klasa encji: Article, znajduje się w src/Model/Entity/Article.php
  • Klasa kontroler: ArticlesController, znajduje się w src/Controller/ArticlesController.php
  • Szablon vidoku, znajduje się w src/Template/Articles/index.ctp

Dzięki użyciu konwencji nazw, CakePHP wie, gdzie kierować żądanie http://example.com/articles/. Mapuje je jako akcję index() w kontrolerze ArticlesController, gdzie model Articles jest automatycznie dostępny (i automatycznie powiązany do tabeli ‘articles’ w bazie danych) i renderowany do pliku widoku. Żadne z tych relacji nie zostało skonfigurowane w inny sposób niż poprzez tworzenie klas i plików zgodnie z konwencją, i nie trzeba nic tworzyć ręcznie.

Teraz, gdy zostałeś wprowadzony do podstaw CakePHP, możesz teraz otworzyć Bookmarker Tutorial by zobaczyć, jak wszystko zostało dopasuje konwencjami.