Стандарты разработки на платформе 1С-Битрикс

В данном руководстве описаны рекомендуемые техники при разработке на платформе 1С-Битрикс / 1C-Bitrix (далее - Битрикс).

Если вы заметили ошибку и хотите внести исправление или дополнение, пожалуйста, не стесняйтесь делать pull request или связываться напрямую.

Приветствуется любая помощь.

PHP

• Код PHP должен быть написан в соответствии со стандартом PSR-1.

• Стиль написания кода должен соответствовать стандарту PSR-2.

• В конечном итоге придерживаемся правил форматирования (ядро D7) от разработчиков системы.

Оформление исходного кода

• Используйте кодировку UTF-8 без BOM для файлов с исходным кодом.

• Используйте Unix-style окончания строк LF. Никаких CR+LF.

• Используйте сокращенные теги <? и <?=.

  // bad
  <?php echo .. ?>
  
  // good
  <?= .. ?>

• Используйте ТАБ для каждого отступа. Никаких пробелов для блоков кода.

Общие положения

• При добавлении кода в файл init.php группируйте код в классы и выносите их в отдельные файлы.

• При подключении файлов используйте только функции Битрикса. Цитата:

Поддержка Bitrix Framework русских (и прочих) символов в названиях публичных файлов накладывает определённые ограничения на работу: недопустимы прямые вызовы

• к файлам, имена которых выбираются пользователями,
• к папкам, имена которых выбираются пользователями,
• к файлам и папкам, которые могут лежать в папках, имена которых выбираются пользователями. Недопустимы вызовы любых прямых методов работы с файловой системой: include, require, fopen, filesize, unlink, file_exists и т.д. Документация Битрикс CBXVirtualIo

`init.php`
```php
// bad
// SomeClass
include('../some_file.php');

//good
// SomeClass
$APPLICATION->GetFileContent('../some_file.php');
```

• Не используйте цифровые значения в GetList, GetByID и схожих методах, которые принимают различные ID. Создайте файл со всеми необходимыми константами и используйте их имена.

  // bad
  $comments = CIBlockElement::GetList([], ["IBLOCK_ID" => 12]);

  1. У каждой константы должно быть говорящее имя и комментарий.

  2. Файл constants.php:

     // ИБ с комментариями пользователей
     const COMMENTS_IBLOCK_ID = 12;

  3. Подключите этот файл в init.php

     //Константы проекта
     $APPLICATION->GetFileContent($_SERVER["DOCUMENT_ROOT"] . '/bitrix/php_interface/includes/constants.php');

  4. Используйте константу

     $comments = CIBlockElement::GetList([], ["IBLOCK_ID" => COMMENTS_IBLOCK_ID]);

• Используйте Bitrix IBlock Tools, обсуждение.

• При выборках данных (например, GetList) обязательно указывайте поля, которые нужны для дальнейших манипуляций, кроме случаев, когда нужны все поля:

  // good - Обязательно указывайте поля для выборки
  $arSelect = ["ID", "IBLOCK_ID", "NAME", "DATE_ACTIVE_FROM"];
  ...
  $res = CIBlockElement::GetList([], $arFilter, false, [], $arSelect);

• При необходимости выбрать несколько элементов по ID, обязательно используйте GetList вместо GetByID:

  // bad
  $element1 = CIBlockElement::GetByID(1);
  $element2 = CIBlockElement::GetByID(2);
  
  // good
  $elements = CIBlockElement::GetList([], [
      "ID" => [1, 2]
      ]);

• Не используйте прямые запросы к базе данных, вся работа только через API.

• Если к файлу не предусмотрен прямой доступ через WEB, в первой строке файла добавьте:

  <?if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true) die();?>

Отладка

Важно

Логирование замедляет работу системы и может являться брешью в безопасности

Вывод на экран

• Воспользуйтесь модулем Bitrix Debug, GitHub.

Вывод в файл

• api_help

1. Определите константу LOG_FILENAME в файле /bitrix/php_interface/dbconn.php, задавая путь к лог-файлу за пределами DOCUMENT_ROOT.

   // определяем константу LOG_FILENAME, в которой зададим путь к лог-файлу
   define("LOG_FILENAME", $_SERVER["DOCUMENT_ROOT"]."/../log.txt");

2. Отправьте сообщение в лог

   AddMessage2Log("Произвольный текст сообщения", "module_id");

   Пример:

   AddMessage2Log( print_r($arResult, true) );

SQL

• Определите переменную DBDebugToFile для логирования всех SQL запросов.

  $DBDebugToFile = true;

Работа с компонентами

• Шаблонам компонентов давайте осмысленные названия и в каждом проекте придерживайтесь общего стиля. Например, раздел/страница_сайта.Название.Тип

  Примеры:

  • index.user.auth
  • profile.orders.list
  • cart.products.additional

• Стандартные компоненты не модифицируются. Если возникнет такая необходимость — создайте копию компонента в своем пространстве имен в каталоге /дщсфд/components/.

• НЕ РЕКОМЕНДУЕТСЯ делать любые манипуляции с данными в файле template.php. При необходимости правки логики стандартных компонентов, но недостаточной для того, что делать свой используются файлы result_modifier.php и component_epilog.php

• РЕКОМЕНДУЕТСЯ использовать файлы style.css и script.js в шаблонах только если они переопределяют стандартное поведение схожих элементов. РЕКОМЕНДУЕТСЯ оставить комментарий об этой особенности.

Кэширование

• Кэширование компонентов не отключается. Практически не существует задач, которые нельзя решить с включенным кэшированием.

  Исключение:

  • Во время разработки полностью отключайте кэширование - это сэкономить вам много времени.

• Подключайте js и css файлы только через предназначенный для этого API:

  • CMain::AddHeadScript
  • CMain::SetAdditionalCSS

• Если файлы ресурсов подключены неправильно, высока вероятность, что браузеры начнут их активно кэшировать. Не забывайте про специализированные расширеня для браузеров:

  • Chrome Clear Cache

• НЕЛЬЗЯ вставлять код вызова компонента внутрь файла template.php другого компонента.

  Это противоречит идеологии разделения даннах и представления (см. выше) и влечет двойное кэширование.

Работа с шаблонами

• РЕКОМЕНДУЕТСЯ использовать минимальное количество шаблонов.
• РЕКОМЕНДУЕТСЯ подключать header.php и footer.php из одного места для всех шаблонов, если это позволяет дизайн и верстка.
• РЕКОМЕНДУЕТСЯ общие картинки, скрипты и стили шаблонов сохранять в одном месте, например, в /bitrix/templates/.default/.

Структура шаблона

• В каталоге шаблона остаются только необходимые для Битрикс файлы - header.php, footer.php, styles.css и т.д.
• Включаемые файлы располагаются в каталоге includes
• Все дополнительные файлы (скрипты, изображения и т.д.) располагаются в каталоге assets:
  • js - свои скрипты и однофайловые библиотеки
  • css - свои стили и однофайловые библиотеки
  • images - изображения, спрайты, иконки
  • fonts - шрифты
  • остальные библиотеки и фреймворки располагаются в каталогах, названия которых совпадают с названием и версией библиотеки, при этом сохраняется внутренняя структура дистрибутива.
    • Документацию, примеры и доп. файлы можно удалить.

Пример:

/local/templates/<название_шаблона>/
├── header.php
├── footer.php
├── styles.css
├── templaye_styles.css
│
├── components/
|   ├── ..
│
├── assets/
│   ├── js/
|   |   ├── lib/
|   |   |   ├── jquery.min.js
│   |   |
|   |   ├── custom.js
│   |
│   ├── css/
|   |   ├── ..
│   |
│   ├── images/
|   |   ├── ..
│   |
│   └── bootstrap-3.0.0/
│       ├── js/
│       ├── css/
  ...

Работа с инфоблоками

• Названия свойств инфоблоков должны быть:

  1. в верхнем регистре;
  2. осмысленными (используйте связку сущность_наименование);
  3. слова разделаются подчеркиванием.

  Пример:

  • Имя пользователя: USER_NAME
  • Валюта заказа: ORDER_CURRENCY
  • Список заказов: ORDER_LIST