Приветствую всех на Хабре. Я Сергей Михнов, CEO компании Пуск, интегратора Битрикс24. В свое время мы выбрали особый путь – специализацию на коробочной версии Битрикс24. В коммуникациях на сайте или паблишинг площадках мы всегда пишем, что дорабатываем коробку бережно. Решил поделиться, что это значит для нас.

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

Для начала поделюсь требованием к доработкам: 

• Ядро не модифицируется.

• Шаблон портала / компоненты / шаблоны компонентов не копируется.

• Все доработки находятся в папке local, с соблюдением правил описанных в разделе «Организация кода в папке local».

• В доработке не используются конкретные id, все что может измениться при переносе на другую копию портала вынесено в настройки модуля, с возможностью изменять через интерфейс.

• Доработка не должна нарушать работу портала, в случае ее некорректной настройки. 

• К каждой доработке есть инструкция по переносу без участия исполнителя. 

• Запуск нужных скриптов.

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

• Файлы логов располагаются в папке logs или за пределами директории портала. Также предусмотрены механизмы отключения и ротация файлов.

• События агентов логируются в «Журнале событий».

• Ошибки в блоках БП логируются в «Журнал бизнес-процесса»

Правила оформления кода

Контроль качества кода производится при помощи платформы анализа Sonar. Проверка осуществляется посредством интеграции кода в ветку develop, а также при создании / изменении запросов на слияние. 

• Соблюдается стандарт PSR-12. 

• Для массивов используется сокращенная запись.

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

Для качественной и комфортной работы требуется:

• Установить плагин SonarLint, который нужно будет подключить к порталу

• В IDE настроить code style 

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

Также в проекте устанавливается «php-cs-fixer», который правит код в соответствии с конфигурацией local/.php-cs-fixer.php.

Для запуска в директории local выполняется команда «php ./vendor/bin/php-cs-fixer fix», и только после этого следует commit. В этом случае замечания будут отображаться в среде разработки, а большая часть будет автоматически устраняться IDE.

Это правило является основополагающим.

Теперь рассмотрим детально все нюансы осуществления качественных доработок для технических специалистов. 

#NOSONAR

Отключение проверок допускается в следующих случаях:

• Подключение файлов.

• Название классов которые соответствуют требованиям Bitrix Framework.

• Легаси код.

Реализация задач (Git)

Для реализации проектов наша компания использует «git-flow».
Перед выполнением задачи мы создаем ветку от develop с id задачи на портале.

Коммиты в процессе именуются по следующему шаблону:

«[P-{id}] {summary} {note }», где

{id} – id задачи на портале;

{summary} – название задачи на портале;

{note} — дополнительная информация, при необходимости.

После завершения работы создается запрос на слияние в ветку develop, с включенными опциями «Удалить исходную ветку» и  «Объединить историю коммитов». А вслед за созданием запроса на слияние автоматически запустится проверка «sonarqube-check». Если проверка завершится успешно —  проводится ревью кода. 

Если проверка имеет негативный исход —  задача не рассматривается, пока замечания не будут устранены. После их исправления в ходе ревью, код переносится на тестовый стенд по предоставленной инструкции к задаче (по умолчанию это переустановка модуля pusk.ext), и проводится проверка функционала. В случае возникновения замечаний задача возвращается на доработку. 

Перенос доработок

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

• Исполнитель реализует доработку и делает запрос на слияние в ветку develop.

• После прохождения автоматической проверки кода и ревью доработка переносится на Test. 

• Происходит тестирование доработки. Если появляются замечания по описанному в задаче функционалу или ломается уже реализованный функционал, то она возвращается на доработку (возвращаемся к шагу 1). 

• Задача завершается.

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

Организация кода в папке local

Структура каталога выглядит следующим образом:

Допускается

• Создание дополнительных модулей

• Подключение через автозагрузку каталога классов с соблюдением PSR-4.

Ниже подробнее разберем функционал каждой папки

Activities

Пользовательские блоки для бизнес-процессов

Components

Папка с компонентами. На первом уровне пространство имен должно соответствовать id нашего модуля с которым связан компонент. Они реализуются только на классах (через component.php  категорически запрещено). 

Js

Содержит расширения (extensions). Используется во всех случаях когда нужен js код, который будет использоваться в нескольких компонентах или для подключения на событиях.

Modules / pusk.ext

Модуль по умолчанию для всех доработок на портале. В случае разработки функционала, который планируется использовать на нескольких порталах мы создаем отдельный модуль. 

Agent

Содержит агенты, реализованные в модуле.

Cli

Содержит все консольные скрипты, реализованные на базе пакета symfony/console. 

Handler

Содержит обработчики событий. На первом уровне мы создаём папку с id модуля к которому относится событие. 

Infrastructure

Содержит все классы, которые используются при установке/удалении модуля или относятся к базовым функциям модуля. 

Orm

Содержит классы, которые описывают структуру таблиц в базе данных.

ResultModifier

Содержит классы, которые используются при кастомизации компонентов через шаблон. (См. раздел «templates»).

ServiceLocator

Содержит классы для подмены через сервис локатор.

Php_interface

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

В файле init.php подключаются нужные файлы или модули.

При потребности подмены классов через сервис локатор необходимо использовать файл local/php_interface/include/crm_services.php. В нем реализуется только регистрация классов, вся логика реализуется в пространстве имен Pusk\Ext\ServiceLocator модуля. 

Templates

В файле components.php описана логика встройки в компонент перед выводом шаблона. Для мы создаем в папке templates/.default/components/bitrix аналогичную структуру целевого компонента. Для комплексных компонентов вместо файла template.php указывается соответствующий файл. 

template.php — содержит только проверку на подключение из ядра (B_PROLOG_INCLUDED). Он нужен для идентификации шаблона и не будет подключаться при его обработке.

result_modifier.php — в этом файле реализуется необходимая логика. Если число строк кода более 5 — она выносится в Pusk\Ext\ResultModifier

Tests

Содержит тесты. Структура соответствует пространству имен тестируемых классов.

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