yii/docs/guide/ru/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 рекомендует именовать переменные, функции и классы, используя CamelCase, что подразумевает написание
каждого слова в имени с большой буквы и соединение их без пробелов.
Первое слово в имени переменных и функций должно быть написано в нижнем регистре, чтобы отличать их от имён
классов (например, `$basePath`, `runController()`, `LinkPager`).
Для полей класса с видимостью `private` рекомендуется
использовать знак подчеркивания в качестве префикса (например, `$_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>