voicon/bitrix-code-standard

Стандарты программирования для платформы 1С-Битрикс

Стандарты программирования для платформы 1С-Битрикс

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

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

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

Часть описанных в этом разделе требований уже указана в стандартах, приведенных выше, но отметим особенно важные.

• РЕКОМЕНДУЕТСЯ использовать только <?php и <?= теги. Тег <? использовать НЕ РЕКОМЕНДУЕТСЯ.
• РЕКОМЕНДУЕТСЯ использование кодировки UTF-8 без BOM.
• Используйте Tab для каждого отступа. Никаких пробелов для блоков кода.

Отладка

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

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

Вывод в файл

• api_help

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

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

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

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

Пример:

AddMessage2Log( print_r($arResult, true) );

SQL

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

$DBDebugToFile = true;

Базовые правила при разработке под Битрикс

• при добавлении кода в файл init.php РЕКОМЕНДУЕТСЯ выносить логически сгруппированный код в отдельные файлы и подключать их внутри init.php

// SomeClass
require_once __DIR__ . '/include/some_class.php';

• НЕ РЕКОМЕНДУЕТСЯ использовать цифровые значения в GetList, GetByID и схожих методах, которые принимают различные ID. РЕКОМЕНДУЕТСЯ создать файл со всеми необходимыми константами и вызывать их имена. У каждой константы ДОЛЖНО быть «говорящее» именование и комментарий.

Не правильно:

$comments = CIBlockElement::GetList(array(), array('IBLOCK_ID' => 12));

Правильно: Создаем файл constants.php и указываем в нем:

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

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

//Константы проекта
require_once __DIR__ . '/includes/constants.php';

Используем константу

$comments = CIBlockElement::GetList(array(), array('IBLOCK_ID' => COMMENTS_IBLOCK_ID));

• при выборках данных (например, GetList) ОБЯЗАТЕЛЬНО указывать поля (для GetList это 5-ый параметр arSelectFields), которые нужны для дальнейших манипуляций, кроме случаев, когда нужны все поля;

$filter = array('IBLOCK_ID' => COMMENTS_IBLOCK_ID);
$select = array('ID', 'NAME');
$comments = CIBlockElement::GetList(array(), $filter, false, array(), $select);

• при необходмости выбрать несколько элементов по ID, ОБЯЗАТЕЛЬНО использовать GetList вместо GetByID

Не правильно:

$element1 = CIBlockElement::GetByID(1);
$element2 = CIBlockElement::GetByID(2);

Правильно:

$elements = CIBlockElement::GetList(array(), array(1, 2));

• НЕ РЕКОМЕНДУЕТСЯ использовать прямые запросы к базе данных без крайней необходимости;
• если к файлу не предусмотрен прямой доступ ОБЯЗАТЕЛЬНО в первой строке файла добавить

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

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

• РЕКОМЕНДУЕТСЯ давать шаблонам компонентов осмысленные названия и в каждом проекте придерживаться общего стиля. Например, Раздел/страница_сайта.Название.Тип Примеры:
• index.user.auth
• profile.orders.list
• cart.products.additional
• НЕЛЬЗЯ модифицировать стандартные компоненты. Если возникает такая необходимость — создается копия компонента в своем пространстве имен в папке /bitrix/components/
• РЕКОММЕНДУЕТСЯ все шаблоны компонентов сохранять в шаблоне .default в папке /bitrix/templates/.default/
• НЕ РЕКОМЕНДУЕТСЯ делать любые манипуляции с данными в файле template.php. При необходимости правки логики стандартных компонентов, но недостаточной для того, что делать свой используются файлы result_modifier.php и component_epilog.php
• РЕКОМЕНДУЕТСЯ использовать файлы style.css и script.js в шаблонах только если они переопределяют стандартное поведение схожих элементов. РЕКОМЕНДУЕТСЯ оставить комментарий об этой особенности

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

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

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

• ОБЯЗАТЕЛЬНО называть все свойства инфоблоков в верхнем регистре, осмысленно (используя связку сущность-наименование), разделяя слова нижним подчеркиванием. Например:
• Имя пользователя: USER_NAME
• Валюта заказа: ORDER_CURRENCY
• Список заказов: ORDER_LIST
• Использовать уникальные CODE для каждого отдельного инфо-блока. Рекомендуется поставить защиты:

AddEventHandler('iblock', 'OnBeforeIBlockAdd', 'checkCode');
AddEventHandler('iblock', 'OnBeforeIBlockUpdate', 'checkCode');
function checkCode($params)
{
	if (isset($params['CODE']) && $params['CODE'] !== '') {
		CModule::IncludeModule('iblock');

		$iblocks = CIBlock::GetList(array(), array('CODE' => $params['CODE']));
		if ($iblock = $iblocks->Fetch()) {
			$APPLICATION->ThrowException(new CApplicationException('Инфоблок с таким CODE уже существует.'));

			return false;
		}
	}
}

• Рекомендуется использовать библиотеку для простого и быстрого получения ID.

AJAX-обработчики

Довольно часто нужно создать пустую страницу — без вывода шапки и футера, но с возможностью обращаться к классам Битрикс. Например, такое нужно для работы с AJAX. Делается это очень просто. Создаем файл и пишем в нем.

define('NO_KEEP_STATISTIC', true);
define('NOT_CHECK_PERMISSIONS', true);
require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';

Теперь в этом файле можно легко обращаться к любым классам Битрикс. Не забывайте только модули подключить нужные:

CModule::IncludeModule('название_модуля');

Источник