yii/docs/guide/uk/basics.convention.txt

Угоди
=====

Yii ставить угоди вище за конфігурації. Дотримуючись угод, ви зможете створювати серйозні додатки
без необхідності написання та підтримки складних конфігурацій. Звичайно ж, при необхідності Yii може
бути змінений за допомогою конфігурацій практично як завгодно.

Нижче представлені угоди, рекомендовані для програмування під Yii.
Для зручності приймемо, що `WebRoot` — це директорія, у яку встановлений додаток.

URL
---

За замовчуванням, Yii сприймає адреси URL наступного формату:

~~~
http://hostname/index.php?r=ControllerId/ActionId
~~~

GET-змінна `r` представляє [маршрут](/doc/guide/basics.controller#route), 
з якого Yii отримує інформацію про контролер і дію.
Якщо `ActionId` не зазначений, контролер буде використовувати дію за замовчуванням 
(визначену в  [CController::defaultAction]).
Якщо ж `ControllerId` також не зазначений (або змінна `r` відсутня), буде використаний
контролер за замовчуванням (визначений у властивості [CWebApplication::defaultController]).

Використовуючи [CUrlManager] можна створювати й застосовувати більш SEO-дружні адреси URL, такі як 
`http://hostname/ControllerId/ActionId.html`. Ця можливість докладно описана в розділі 
[Красиві адреси URL](/doc/guide/topics.url).

Код
---

Yii рекомендує іменувати змінні, функції та класи, використовуючи ГорбатийРегістр (Camel Case), що має на увазі написання
кожного слова в імені з великої букви та зʼєднання їх без пробілів.
Перше слово в імені змінних і функцій повинне бути написане в нижньому регістрі, щоб відрізняти їх від імен
класів (наприклад, `$basepath`, `runController()`, `LinkPager`). 
Для імен властивостей класу рекомендується використовувати знак підкреслення як префікса (наприклад, `$_actionList`).

Оскільки простори імен не підтримуються версіями PHP до 5.3.0, рекомендується, щоб імена класів були 
унікальними для уникнення конфлікту імен із класами сторонніх виробників. Із цієї причини всі імена класів
фреймворка мають префікс "C".

Особливе правило для імен класів контролерів — вони повинні бути доповнені словом `Controller`. При цьому ідентифікатором
контролера буде імʼя класу з першою буквою в нижньому регістрі та без слова `Controller`.
Наприклад, для класу `Pagecontroller` ідентифікатором буде `page`. Дане правило робить додаток більш захищеним.
Воно також робить адреси URL більш зрозумілими ( приміром, `/index.php?r=page/index` замість
`/index.php?r=PageController/index`).

Конфігурація
------------

Конфігурація — це масив пар ключ-значення, де кожний ключ являє собою імʼя властивості обʼєкта, що конфігурується, 
а значення — початкове значення відповіднї властивості.
Приміром, `array('name'=>'My application', 'basePath'=>'./protected')` ініціалізує властивості `name` і `basePath`
відповідними значеннями.

Будь-які властивості обʼєкта, що доступні для запису, можуть бути зконфігуровані. Якщо деякі 
властивості не зконфігуровані, для них будуть використані значення за замовчуванням. 
При конфігуруванні властивостей рекомендується вивчити відповідний розділ документації, 
щоб уникнути завдання некоректних значень.

Файл
----

Угоди для іменування й використання файлів залежать від їх типів.

Файли класів повинні бути названі так само, як і публічні класи, що містяться в них.
Наприклад, клас [CController] знаходиться в файлі `CController.php`. 
Загальний клас — це клас, який може бути використаний будь-якими іншими класами.
Кожний файл класів повинен містити максимум один загальний клас. Приватні класи 
(класи, які можуть бути використані тільки одним загальним класом) повинні перебувати в одному
файлі із загальним класом.

Файли представлень повинні мати такі ж імена, як і відображення, що містяться в них. 
Приміром, відображення `index` знаходиться в файлі `index.php`. 
Файл відображення — це PHP-скрипт, що містить HTML і PHP-код, в основному для задання відображення
користувальницького інтерфейсу.

Конфігураційні файли можуть іменуватися довільним образом. Файл конфігурації —
це PHP-скрипт, чиє єдине призначення — повертати асоціативний масив, що представляє конфігурацію.

Директорія
----------

В Yii визначений набір директорій для різних цілей. Кожна з них може бути змінена при необхідності.

   - `WebRoot/protected`: це [базова директорія додатку](/doc/guide/basics.application#application-base-directory), 
яка містить всі найбільш важливі з точки зору безпеки PHP-скрипти та файли даних. Псевдонім за замовчуванням для цього шляху 
— `application`. Ця директорія і її вміст повинні бути захищені від прямого доступу з веб. 
Директорія може бути налаштована через [CWebApplication::basePath];

   - `WebRoot/protected/runtime`: ця директорія містить приватні тимчасові файли, згенеровані під час виконання додатку.
Ця директорія повинна бути доступна для запису веб-сервером. Вона може бути налаштована через [Capplication::runtimePath];

   - `WebRoot/protected/extensions`: ця директорія містить всі сторонні розширення. Вона може бути налаштована через 
[CApplication::extensionPath]. Псевдонім за замовчуванням для цього шляху - `ext`;

   - `WebRoot/protected/modules`: ця директорія містить усі [модулі](/doc/guide/basics.module) додатку, 
кожний з яких представлений в окремій піддиректорії. Директорія може бути налаштована через [CWebApplication::modulePath];

   - `WebRoot/protected/controllers`: ця директорія містить файли всіх класів контролерів. 
Вона може бути налаштована через [CWebApplication::controllerPath];

   - `WebRoot/protected/views`: ця директорія містить файли всіх представлень, включаючи відображення контролерів, 
макети та системні представлення. Вона може бути налаштована через [CWebApplication::viewPath];

   - `WebRoot/protected/views/ControllerId`: ця директорія містить файли представлень для окремого класу контролера. 
Тут `ControllerId` є ідентифікатором контролера. Директорія може бути налаштована через [CController::viewPath];

   - `WebRoot/protected/views/layouts`: ця директорія містить файли макетів. Вона може бути налаштована через 
[CWebApplication::layoutpath];

   - `WebRoot/protected/views/system`: ця директорія містить файли системних представлень 
(використовуються для виводу повідомлень про помилки і виключення). 
Вона може бути налаштована через [CWebApplication::systemViewPath];

   - `WebRoot/assets`: ця директорія містить файли ресурсів (приватні файли, які можуть бути 
опубліковані для доступу до них із веб). Директорія повинна бути доступна для запису процесами веб-серверу. 
Вона може бути налаштована через [CAssetManager::basePath];

   - `WebRoot/themes`: ця директорія містить різні теми оформлення, які доступні додатку. 
Кожна піддиректорія містить окрему тему з іменем, що збігаються з назвою піддиректорії. 
Директорія може бути налаштована через [CThemeManager::basePath].

База даних
-----------

Більшість додатків зберігають дані в БД. Ми пропонуємо угоди для таблиць та атрибутів БД. 
Варто відзначити, що Yii не вимагає суворої відповідності їм.

   - Таблиці й атрибути іменуються в нижньому регістрі.

   - Слова в назві розділяються підкресленням (наприклад, `product_order`).

   - В іменах таблиць використовується або однина, або множина, але не обидва відразу. 
Ми рекомендуємо використовувати однину.

   - Імена таблиць можуть містити префікс. Наприклад, `tbl_`. Це особливо корисно
коли таблиці нашого додатку містяться в БД, що використовується одночасно іншими
додатками.

<div class="revision">$Id: basics.convention.txt 3225 2011-05-17 23:23:05Z alexander.makarow $</div>