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

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

Ключевые слова необходимо, недопустимо, требуется, следует, не следует, рекомендуется, не рекомендуется, возможно, необязательно в данном документе должны интерпретироваться в соответствии с требованиями RFC 2119.

PHP

Необходимо придерживаться правил форматирования (ядро d7) от разработчиков Битрикс.
Код необходимо оформлять в соответствии со стандартом PSR-1 если он не противоречит правилам в первом пункте и этом документе
Стиль написания кода необходимо поддерживать в соответстви со стандартом PSR-2 если он не противоречит правилам в первом пункте и этом документе.

Отличия от `PSR-1` и `PSR-2`

Кодировка UTF-8 обязательна только для новых проектов
Отступы не 4 пробелами, а табами размером 4 символа
Открывющая фигурная скобка в управляющих конструкциях и замыканиях всегда с новой строки
Ключевое слово после закрывающей фигурной скобки также всегда с новой строки (else, elseif и прочее)

Основные требования

Рекомендуется использовать только <?php и <?= теги. Тег <? использовать не рекомендуется.
Обязательно использовать кодировку UTF-8 без BOM (только для новых проектов)
Обязательно использовать Unix-style окончания строк LF. Никаких CR+LF.
Обязательно использовать ТАБ для отступов

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

Недопустимо добавлять код няпрямую в файл init.php: группируйте его в классы и выносите в отдельные файлы

Классы следует подключать автозагрузкой (не require или include)
Пример:

<?php

if (!defined('B_PROLOG_INCLUDED') || B_PROLOG_INCLUDED !== true) die();

\Bitrix\Main\Loader::registerAutoLoadClasses($module = null, array(
   '\\Citrus\\ClassName' => '/local/lib/Citrus/ClassName.php',
));

На новых проектах всю работу проводите в папке /local/, папка /bitrix/ не должна изменяться
Не следует использовать цифровые значения в GetList, GetByID и схожих методах, которые принимают различные ID. Создайте файл или класс со всеми необходимыми константами и используйте их имена.
```
// bad
$comments = CIBlockElement::GetList(Array(), Array("IBLOCK_ID" => 12));
```
1. У каждой константы должно быть говорящее имя и комментарий.
2. Файл constants.php:
```
<?php

// ИБ с комментариями пользователей
const COMMENTS_IBLOCK_ID = 12;
```
3. Подключите этот файл в init.php
4. Используйте константу
```
<?php

$comments = CIBlockElement::GetList(Array(), Array("IBLOCK_ID" => COMMENTS_IBLOCK_ID));
```
При выборках данных (например, GetList) обязательно указывайте поля, которые нужны для дальнейших манипуляций, кроме случаев, когда нужны все поля:
```
<?php

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

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

<?php
// bad
$element1 = CIBlockElement::GetByID(1);
$element2 = CIBlockElement::GetByID(2);

// good
$elements = CIBlockElement::GetList(Array(), Array(1, 2));

Не используйте прямые запросы к базе данных, вся работа только через API.
Если к файлу не предусмотрен прямой доступ через WEB, в первой строке файла добавьте:
```
<?php

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

Отладка

Зачем нужен XDebug?

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

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

Поддерживается также выполнение произвольного кода на точке останова, а также и ряд других полезных при отладке функций.

В целом, расширение нужно, в первую очередь, для экономии времени программистов, так как позволяет быстро локализовать ошибку в коде.

Википедия

Статьи

Старая статья от IBM о преимуществах отладки в PHP
Настраиваем PhpStorm
Настраиваем Sublime Text

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

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

Примеры:
- index.user.auth
- profile.orders.list
- cart.products.additional
Недопустимо изменение стандартных компонентов или их шаблонов. Если возникнет такая необходимость — создайте копию компонента в своем пространстве имен в каталоге /local/components/.
На многосайтовых проектах рекомендуется общие шаблоны компонентов сохранять в шаблоне .default в каталоге /local/templates/.default/.
Не рекомендуется делать любые манипуляции с данными в файле template.php шаблона компонента.
При необходимости правки логики стандартных компонентов, но недостаточной для того, чтобы делать свой, используются файлы result_modifier.php и component_epilog.php

Кэширование

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

Исключение:
- Во время разработки полностью отключайте кэширование - это сэкономит вам много времени.
Подключайте js и css файлы только через предназначенный для этого API:
- Bitrix\Main\Page\Asset::getInstance()->addJs(), Asset::getInstance()->addCss(), Asset::getInstance()->addString()
- В файле template.php: $this->addExternalCss() и $this->addExternalJs()
Если файлы ресурсов подключены неправильно, высока вероятность, что браузеры начнут их активно кэшировать. Не забывайте про специализированные расширеня для браузеров:
- Chrome Clear Cache
НЕЛЬЗЯ вставлять код вызова компонента внутрь файла template.php другого компонента.

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

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

Следует использовать минимальное количество шаблонов (сайтов и компонентов), хранить одинаковые шаблоны компонентов в /local/templates/.default/
Рекомендуется подключать header.php и footer.php из одного места для всех шаблонов, если это позволяет дизайн и верстка.
Рекомендуется общие картинки, скрипты и стили шаблонов сохранять в одном месте, например, в /local/templates/.default/.

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

В каталоге шаблона остаются только необходимые для Битрикс файлы - header.php, footer.php, styles.css и т.д.
Включаемые файлы располагаются в каталоге includes в корне сайта
Все дополнительные файлы (скрипты, изображения и т.д.) располагаются в каталоге assets шаблона:
- js — свои скрипты и однофайловые библиотеки
- css — свои стили и однофайловые библиотеки
- images — изображения, спрайты, иконки
- fonts — шрифты
- подключать свои скрипты и стили и строки в <head> с помощью методов Bitrix\Main\Page\Asset::getInstance()->addJs, Bitrix\Main\Page\Asset::getInstance()->addCss, Bitrix\Main\Page\Asset::getInstance()->addString
- проверять работу скриптов и корректность верстки со всеми включенными опциями главного модуля "Оптимизация CSS"
- остальные библиотеки и фреймворки располагаются в каталогах, названия которых совпадают с названием и версией библиотеки, при этом сохраняется внутренняя структура дистрибутива. — Документацию, примеры и доп. файлы можно удалить.

Пример:

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

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

Названия свойств инфоблоков должны быть:
1. в верхнем регистре;
2. осмысленными (используйте связку сущность_наименование);
3. слова разделаются подчеркиванием.
Пример:
- Имя пользователя: USER_NAME
- Валюта заказа: ORDER_CURRENCY
- Список заказов: ORDER_LIST

Git →

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

# PHP

# Отличия от PSR-1 и PSR-2

# Основные требования

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

# Отладка

# Зачем нужен XDebug?

# Статьи

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

# Кэширование

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

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

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