2. Руководство разработчика › 2.2 Устройство проекта › Принятые обозначения

Для облегчения восприятия кода и совместимости модулей разных разработчиков мы настоятельно рекомендуем придерживаться следующих соглашений об именовании.

Имена файлов

Корневые скрипты и HTML-шаблоны — нижний регистр, слова разделяются знаком подчёркивания:

index.php
page_catalog.php
main.htm
page_404.htm
item_product.htm

Модульные скрипты строятся по схеме из трёх частей, разделённых подчёркиванием:

{компания}_{группа}_{назначение}.php

Примеры:

melbis_base_page.php       — базовый роутер страниц
melbis_store_card.php      — карточка товара
melbis_cataloge.php        — каталог
melbis_inc_logic.php       — библиотека бизнес-логики
melbis_block_slider.php    — слайдер
melbis_client_auth.php     — авторизация клиента

У библиотек частей четыре: слово inc занимает место группы, а собственная группа библиотеки переезжает в следующую часть имени — об этом ниже, в разделе «Группы модулей».

Кроме самого кода у каждого модуля есть параметры — кеш, входные данные, список таблиц, подключённые библиотеки. Они задаются в окне «Среда разработки», в правой панели рядом с редактором кода, и хранятся вместе с модулем. Подробнее это описано в разделе «Модульные скрипты».

Группы модулей

Группа в имени модуля несёт смысловую нагрузку и определяет отображение в дереве «Среды разработки». Зарезервирована только одна группа — inc (допускается также include или пустое значение). Модули с такой группой являются библиотеками: у них не может быть HTML-шаблонов, и парсер их не вызывает напрямую — их функции используются другими модулями.

Все остальные имена групп (base, store, cataloge, basket, client, block, cron и любые другие) вы определяете самостоятельно исходя из архитектуры проекта. Группа — это просто способ организовать модули в дереве файлов.

melbis_base_page.php       — обычный модуль (группа base)
melbis_store_card.php      — обычный модуль (группа store)
melbis_block_slider.php    — обычный модуль (группа block)

Группы библиотек

У библиотек слово inc занимает место группы, поэтому собственная группа переезжает в следующую часть имени:

{компания}_inc_{группа}_{назначение}.php

В дереве «Среды разработки» библиотеки раскладываются по этой группе — рядом с обычными модулями и на том же уровне, но со своим значком. Общей папки inc, куда сваливались бы все библиотеки проекта, больше нет:

melbis
    auth          melbis_inc_auth.php
    logic         melbis_inc_logic.php
    web           melbis_inc_web_callback.php
                  melbis_inc_web_topic.php
    base          melbis_base_footer.php
                  melbis_base_head.php
                  melbis_base_header.php
                  melbis_base_page.php
    basket        melbis_basket.php
    cataloge      melbis_cataloge.php
                  melbis_cataloge_sub.php

Назначение можно опустить, если библиотека в группе одна: melbis_inc_logic.php — это группа logic без назначения, а melbis_inc_web_callback.php — группа web, назначение callback.

Смысл в том, чтобы библиотека лежала рядом с модулями, которые ею пользуются: melbis_inc_web_callback и melbis_inc_web_topic относятся к веб-части проекта и собраны в группу web, а не растворены среди всех прочих библиотек.

Функции в модульных скриптах

Каждый обычный модуль содержит главную функцию — её имя полностью совпадает с именем файла модуля, написанным в верхнем регистре. Именно эту функцию вызывает парсер:

// Файл: melbis_store_card.php
function MELBIS_STORE_CARD($mVars)
{
    ...
}

Исключение — библиотечные модули группы inc. Парсер их не вызывает, поэтому главной функции у них нет. Вместо этого они содержат набор вспомогательных функций, которые явно вызываются из других модулей.

Вспомогательные функции внутри того же модуля именуются с префиксом главной функции, а собственное имя пишется PascalCase — каждое слово с заглавной, без подчёркиваний:

function MELBIS_STORE_CARD_Price($mTpl, $mId)
{
    ...
}

function MELBIS_STORE_CARD_Features($mTpl, $mId)
{
    ...
}

Смена регистра отмечает границу имени: слева от неё — модуль, справа — функция. Граница видна и глазу, и инструментам — IDE и линтер раскладывают имя, не заглядывая в дерево модулей, а поиск по Price находит и объявление, и вызовы — включая короткие через UnitFunc (см. «Служебные методы»). Заодно точка входа отличается от помощников сама собой: у неё Pascal-хвоста нет.

Аббревиатуры в хвосте пишутся как слова: SmsUrl, XmlLoad — не SMSUrl, иначе граница префикса теряется.

Такой подход гарантирует уникальность имён функций в глобальном пространстве имён PHP и позволяет сразу понять, к какому модулю относится та или иная функция.

Функции в библиотечных модулях (inc) именуются по той же схеме — с префиксом имени библиотеки:

// Файл: melbis_inc_logic.php
function MELBIS_INC_LOGIC_OrderCreate(...)  { ... }
function MELBIS_INC_LOGIC_OrderCalc(...)    { ... }
function MELBIS_INC_LOGIC_OrderEdit(...)    { ... }

Проекты со строчными хвостами (MELBIS_INC_LOGIC_order_create) работают как раньше — PHP не различает регистр в именах функций. Pascal-хвост — соглашение для нового кода.

Имена в модуле с пространством имён

Приставка в именах нужна ровно потому, что все функции PHP лежат в общем пространстве. Модуль или библиотека, объявившие собственное пространство, от неё избавляются: имя файла переезжает в строку namespace, а в именах функций остаётся один Pascal-хвост.

// Файл: melbis_store_card.php
namespace MELBIS_STORE_CARD;

function Main($mVars)  { ... }
function Price($mTpl, $mId)   { ... }
function Features($mTpl, $mId) { ... }

Главная функция в таком файле называется Main: имя модуля уже написано выше, повторять его незачем. Регистр у неё теперь тот же, что у помощников, — отличает её не написание, а само имя, закреплённое за точкой входа. Парсер ищет обе формы, так что плоские модули с главной функцией по имени файла работают по-прежнему.

Полное имя функции при этом меняется предсказуемо: подчёркивание перед хвостом становится обратным слешем — MELBIS_STORE_CARD_Price превращается в MELBIS_STORE_CARD\Price. Граница между модулем и функцией из соглашения становится конструкцией языка, а поиск по Price по-прежнему находит и объявление, и вызовы.

Подробнее о переводе модуля и о том, что при этом проверить, — в разделе «Модульные скрипты».

Переменные в PHP-скриптах

Тип переменной Правило Пример
Входные параметры функции Начинаются с $m, далее camelCase $mVars, $mTopicId, $mTpl
Локальные переменные Нижний регистр, слова через _ $id, $item_count, $command
PHP-константы Верхний регистр, слова через _ MELBIS_CACHE, MELBIS_LANG

В главной функции модуля массив входных параметров принято называть $mVars.

Псевдонимы таблиц в SQL

Псевдоним таблицы — аббревиатура из первых букв слов её имени (префикс {DBNICK}_ не считается): {DBNICK}_user_task → ut, {DBNICK}_user_group → ug, {DBNICK}_user → u. Если таблица встречается в запросе несколько раз или нужен признак роли — к аббревиатуре добавляется признак через подчёркивание: u_author, u_exec, ug_main.

Правило не косметическое: на нём построена подсказка полей в «Среде разработки». Набранное ut. или u_author. IDE сводит к таблицам, подпадающим под сокращение, и показывает их поля.

$command = "SELECT ut.id, ut.name, ut.state_key,
                   u_author.login AS author, u_exec.login AS executor
              FROM {DBNICK}_user_task ut
         LEFT JOIN {DBNICK}_user u_author
                ON u_author.id = ut.user_id
         LEFT JOIN {DBNICK}_user u_exec
                ON u_exec.id = ut.exec_id
             WHERE ut.state_key <> 'kClose'
           ";

Значения в текст запроса не вклеиваются: в SQL стоит плейсхолдер :ИМЯ в верхнем регистре, а значение кладётся в массив параметров — подробнее в разделе «Работа с базой данных».

Ключи в HTML-шаблонах

Все ключи шаблонизатора пишутся в верхнем регистре, слова разделяются знаком подчёркивания:

{TITLE}
{PAGE_NAME}
{PRODUCT:PRICE_OLD}
{#ITEMS}
    <a href="?id={ID}">{NAME|html}</a>
{ITEMS#}