Почему следует переносить проект на bitrix. Автоматическое развертывание проектов на php

Считаем, что принято решение делать сайт на CMS и в качестве CMS был выбран битрикс. Дизайнер отрисовал картинку, верстальщик сделал html+css+js код и дальше начинает работу серверный программист. С чего начать проект? Как лучше организовать код? Об этом я хочу поговорить в данной статье. Здесь я не ставлю задачу объяснить каждую деталь подробно, не ставлю задачу показать прямо конкретные шаги, вроде выполните первое, выполните второе и т.д. Здесь я постараюсь обрисовать общую картину. Я хочу показать как должен быть устроен проект на битриксе с моей точки зрения. Если у вас есть какие то замечания, дополнения или уточнения, то пишите в комментарии. Было бы любопытно сравнить разные подходы к формированию структуры проекта.

Начну с банальностей. Любой проект начинается с папки, так что создайте папку в любом удобном для вас месте. Эта папка будет корнем сайта, то есть если вы редактируете файл index.php в этой новой папке, то это все равно что вы редактируете файл /index.php на сайте (после синхронизации естественно). Ну это я думаю и так понятно. Если вы пользуетесь IDE, то можете создать новый проект через меню редактора, но суть та же останется - будет создана новая папка.

Далее, сразу после создания папки, пока папка пуста делайте из этой папки репозиторий для системы контроля версий. Зачем нужен контроль версий и что это такое вы можете прочитать . Я пользуюсь гитом (git), так что для старта репозитория просто выполняю git init в нужной папке. Вы можете создать репозиторий любым удобным для вас способом. Например можно поставить «tortoseGit» под винду, это визуальный интерфейс, он добавляет новые пункты в контекстное меню по правой кнопке мыши в папке. Мне он кажется довольно простым и удобным, просто кликая мышкой без консоли можно управлять репозиторием.

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

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

Есть множество всяких красивых схем ветвления, отдельная ветка под разработку, рабочая ветка, ветки по фичам, тэги версий и т.д. Все это безусловно круто, но если вы не понимаете зачем это все нужно, то просто отправляйте все в одну ветку master последовательно и не заморачивайтесь с ветками вообще. Все эти схемы ветвления предназначены во первых для группы разработчиков, и во вторых для запущенного или близкого к релизу проекта. Если вы понимаете зачем нужны ветки и как ими пользоваться то этот раздел статьи вам не очень то и нужен 🙂

В битриксе довольно много всякого функционала и соответственно много всяких API функций. Вызов API можно конечно делать и вручную, прямо писать каждый раз название функции, либо открывать документацию и копировать, но гораздо удобнее настроить автодополнение в IDE. Лично я пользуюсь phpstorm от jetbrains, поэтому покажу настройку автодополнения именно тут. Для настройки автодополнения нам понадобится папка /bitrix/modules/ в исходных кодах, то есть ставите где-то битрикс, активируете его, обновляете до последней доступной версии и скачиваете из поставленного битрикса папку /bitrix/modules/. Битрикс не обязательно должен быть активированным, от шифрования кода они уже давно отказались, так что я думаю пойдет /bitrix/modules/ даже от пробной версии, но честно говоря не проверял.

После того как скачаете папку /bitrix/modules/, откройте phpstorm. У вас будет примерно такая картинка перед глазами

Окно нового проекта

Сделайте двойной щелчок мыши слева по строке «External Libraries». Откроется окошко добавления внешней библиотеки. Нажмите в этом окошке плюсик и укажите путь до скачанной папки /bitrix/modules/. После индексации папки, везде во всех файлах будет работать автодополнение по основным функциям. Будет работать переход по ctrl+клик на название функции, можно быстро посмотреть что именно происходит внутри конкретных функций ядра.

Папку /bitrix/modules/ можно использовать одну и ту же для многих проектов. В битриксе изменения происходят довольно часто, но все же прям кардинально они очень редко что меняют. Названия классов и функций, аргументы функций и т.д. как правило остаются без изменений очень долгое время. Так что папку /bitrix/modules/ вполне достаточно обновлять раз в полгода по выходу мажорных версий.

Верстальщик как правило присылает результат в виде папки с html файлами и дополнительными подпапками типа /css/, /images/, /fonts/, /js/ и т.д. То есть собственно страницы сайта которые уже можно открывать в браузере и всякие стили и скрипты для этих страниц. Сразу же закиньте все присланное верстальщиком в корень проекта. Если в верстке используется gulp, grunt, sass, postcss и т.д. и вы верстку не планируете трогать, то достаточно закинуть скомпилированный проект, если планируете править верстку с использованием сборщиков проекта, то вы я думаю и так знаете что делать. Итого без сборщика проекта в корне у вас будет лежать папка /project_name или /verstka/ или еще что в которой лежат html файлы + все что в этих файлах используется. Это очень удобно, можно будет сразу присылать заказчику ссылку на верстку и ссылку на интегрированную в битрикс страницу, типа было и стало, ну либо самому сравнивать если вы собственный проект разрабатываете. Кроме того можно будет сразу брать нужные html куски из верстки не закрывая и не переключаясь из IDE. В дальнейшем, по завершении интеграции эту папку естественно стоит удалить.

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

Вообще вся работа будет вестись в папке local. По большей части это «/local/templates», «/local/php_interface/», «/local/modules/» и «/local/components/». Да, иногда требуется править и страницы публичной части, то есть например /index.php, или /about/index.php, но там практически всегда будут только вызовы компонентов, бывают и особо сложные разделы где много чего прямо на публичных страницах приходится делать, но не часто.

Преимущество папки local в том, что вы точно знаете, что любой код который там лежит был написан именно под этот проект. В папке /bitrix/ сильно дофига служебных и просто не нужных файлов, всякие старые или демонстрационные шаблоны, dbconn.php который отвлекает от init.php и т.д.. В общем чтобы найти что-то в папке /bitrix/ придется приложить больше усилий, потратить больше внимания на каждую операцию. В системе контроля версий не нужно писать огромный.gitignore с перечислением всех служебных папок (попробуйте например добавить в контроль версий только /bitrix/php_interface/init.php и проигнорировать dbconn.php из этой же папки), мы просто весь /bitrix/ игнорируем, а весь /local/ храним в репозитории. Проще говоря папка local гораздо удобнее.

То есть для нового проекта обязательно создаем папку /local/. В ней вам гарантированно потребуется папка templates с шаблоном сайта.

Для начала создайте папку с шаблоном /local/templates/template_name/, либо /local/templates/.default/ если она вам больше нравится. Далее смотрите папку с версткой и копируете оттуда вообще все за исключением html кода в папку с шаблоном. То есть из верстки нужно взять все стили, все скрипты, все картинки, все шрифты и т.д. и положить их в папку с шаблоном. Причем все относительные пути надо сохранять. То есть копируем с сохранением структуры. Если верстальщик грамотный, то ни одного абсолютного пути он не напишет, все картинки будут браться из папки «../images/», а не «/images/», то есть из рядом лежащей папки, вне зависимости от того на какой глубине они лежат.

Весь глобальный шаблон сайта на битриксе это по сути два файла header.php и footer.php в папке с шаблоном. Что должно быть в файле header.php на мой взгляд? Вот примерно такое

Практически на всех сайтах, которые меня просят доработать, в шаблоне я вижу либо старые варианты подключения скриптов и стилей $APPLICATION->AddHeadScript(‘src’), либо же вообще оставшееся от верстки подключение тэгами и . Между тем уже давно в битриксе есть штатное удобное подключение, получаем экземпляр класса \Bitrix\Main\Page\Asset и дальше функциями addJs() и addCss() подключаем скрипты и стили. Если скрипты и стили подключены в шаблоне сайта, то они объединятся в один файл template_random.css и template_random.js (если это включено в настройках конечно же). Если скрипты и стили тем же классом Asset подключаются в любом другом месте, то они будут добавлены в отдельный файл page_random.css и page_random.js. То есть общие для всех страниц файлы кешируются отдельно от скриптов и стилей нужных для конкретной страницы.

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

Пользоваться файлами style.css и script.js в папке с шаблоном компонента вообще не стоит. Да в целом это может быть удобно когда подключаешь компонент на странице, и автоматом подтягиваются все его стили, ни о чем больше думать не нужно. Однако для правок лазить по папкам всех шаблонов и искать эти кусочные стили дикий геморрой. Поэтому все стили для сайта должны лежать в папке с шаблоном, в подпапке /css/ например. Точно так же и со скриптами, все скрипты должны быть в папке /js/ шаблона. Название у папки может быть любое, главное чтобы не в корне сайта и не в папках с шаблонами компонентов.

Скрипты стоит подключать именно в файле header.php и именно функцией addJs(), даже если в верстке скрипты по модному вынесены в конец страницы. В битриксе, в настройках есть галочка которая переносит все скрипты в конец страницы, вне зависимости от того где они были подключены. Поэтому как то специально извращаться со скриптами не нужно. Гораздо удобнее помнить что вообще все внешние файлы, и css и js подключаются в файле header.php в тэге head.

Сторонние плагины и библиотеки желательно подключать отдельно, чтобы сразу было видно где скрипты написанные специально для этого сайта, а где скрипты которые не нужно трогать. Идеально если верстальщик все внешние скрипты и стили положил в отдельную папку /vendor/. В вышеприведенном коде все внешние скрипты подключены в отдельном блоке с комментарием //VENDOR, к сожалению в этом проекте верстальщик кинул все стили плагинов в общую папку стилей, поэтому css подключены общей кучей.

Еще момент по функции ShowHead(). В последнее время все стали верстать в манере html5, и соответственно мета тэг кодировки отличается от битриксовского. Чтобы полностью соответствовать верстке я заменил функцию ShowHead() на то что она собственно содержит. Только убрал в этой функции вывод одного мета тэга. В принципе можно и полный meta charset вызывать, такой же как в функции $APPLICATION->ShowHead(), и тогда можно собственно саму эту функцию и вызывать.

Если на каких то страницах есть боковая панель слева или справа от основного контента, а на каких то страницах этой панели нет, то на мой взгляд панель надо включать в основной шаблон сайта. Не нужно писать html код панели прямо на самой странице. Например, если боковая панель должна быть в разделе «О компании», папка /about/, то не нужно писать html код в файле /about/index.php, в этом файле должно быть только основное содержимое страницы. Это касается не только боковых панелей, но и вообще любых областей сайта которые отображаются и пропадают в зависимости от раздела. Все такие области условно можно назвать зависимыми областями.

Как именно отображать зависимые области? Если речь идет только о главной странице, то достаточно просто хардкодом прописать в глобальном шаблоне условие $APPLICATION->GetCurDir() == ‘/’. Если область должна как то более гибко отображаться, то можно использовать свойство раздела битрикса. Свойство страницы в данном случае не подходят, так как на момент выполнения файла header.php свойство страницы еще не определено, а вот свойство раздела уже есть. Достаточно в настройках модуля управления структурой прописать отдельное свойство под каждую область и в дальнейшем просто включать и отключать область в нужных местах. Если область по умолчанию должна отображаться везде кроме главной страницы, плюс отключена на нескольких выбранных страницах, то определяем свойство раздела show_area_name = Y в корне сайта, и во всех подразделах область будет отображаться, чтобы значение по умолчанию не влияло на главную страницу прописываем в глобальном шаблоне проверку и на свойство и на папку одновременно.

В качестве примера можете посмотреть код шаблона выше, там еще до объявления DOCTYPE у меня собрано свойство show_left_sidebar и текущая директория. Использовать эти собранные переменные можно так:

Вместо вызова ShowViewContent() можно поставить какую нибудь включаемую область или сразу вызывать нужные компоненты.

Вы практически наверняка будете использовать инфоблоки. Большая часть задач в битриксе решается на инфоблоках и каталог товаров, и новости, и какие сообщения об акциях и т.д. В компонентах одним из параметров передается инфоблок. Многие инфоблоки используются на разных страницах, или даже на одной странице в нескольких местах. Если вы вдруг по каким то причинам решите использовать другой инфоблок, то придется во всех местах где этот инфоблок используется исправлять параметры компонента. Но можно при старте проекта объявить константы по всем инфоблокам, плюс любые другие значимые данные, которые могут использоваться на разных страницах. И дальше во всех местах где используется ID инфоблока новостей, заменить его на константу с ID этого инфоблока.

Создайте файл /local/php_interface/init.php. Создайте файл /local/php_interface/include/constants.php. В файле /local/php_interface/init.php подключите файл /local/php_interface/include/constants.php через require или include. Таким образом файл констант у нас будет выполняться вообще всегда, при каждом открытии страницы. Что должно быть в файле с константами? Собственно сами константы. Объявляем константы так:

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

В том случае когда над проектом работают несколько программистов на разных серверах, либо даже если только один программист собирается перенести функционал с тестового сервера на боевой могут возникнуть проблемы, так как ID инфоблоков могут различаться. Например инфоблоки были созданы в разном порядке, или достаточно всего один раз удалить инфоблок на одном из сайтов, чтобы все последующие инфоблоки даже созданные в верном порядке были под разными ID. При простом копировании вызова компонента будут вызываться разные инфоблоки, то есть например на тестовом выводятся новости из компонента с ID=3, а на боевом инфоблок новостей имеет ID=2. И соответственно при копировании вызова компонента будут не новости отображаться, а какая нибудь фотогалерея.

Чтобы решить проблему с разными ID инфоблоков на разных сайтах константы тоже пригодятся. Достаточно при старте страницы получить инфоблок по его символьному коду и засунуть в константу. Специально для этой цели я написал класс - . Здесь я полный листинг файла приводить не буду, там ничего особенного. Вкратце, что там происходит вообще. Если вы пользуетесь моим классом, то объявляем константу вот так

Define("IBLOCK_ID__CATALOG", IBlockData::getByCode("CATALOG"));

Далее функция проверяет статическую переменную класса $byCode, если эта переменная пуста, то получает полный список инфоблоков, и записывает в эту переменную массив ID инфоблоков, где ключами массива являются коды инфоблоков. Далее функция смотрит элемент массива с ключом переданным в качестве аргумента функции. Если элемент найден по ключу, то возвращает его значение. Итого функция по коду инфоблока возвращает его ID. Полная выборка инфоблоков кешируется стандартным битриксовским кешем на сутки, то есть запрос к БД будет только при первом обращении, а весь следующий день значение будет браться из кеша. В кеш ложатся только пара символьный код - ID, поэтому функция достаточно легкая. Инфоблоки берутся с привязкой к сайту, то есть класс применим при работе с многосайтовостью, по коду вернется ID инфоблока на конкретном сайте.

Выше я привел довольно простой файл констант, в котором только несколько инфоблоков и пара путей. Однако же бывают проекты в котором констант на пару экранов. И если называть константы не задумываясь, то будет хаос. Лично я стараюсь обозначать константы по виду. Например если в константе хранится ID инфоблока, то делаю префикс IBLOCK_ID, если там путь, то префикс PATH. В общем тут строгих правил никаких нет, но все же стоит как-то хотя бы минимально обозначать в названии константы ее значение. Константа «TEST_BLOCK» какая-нибудь вообще непонятно что содержит, особенно если там просто цифра записана.

Со временем у любого программиста накапливается довольно много готового кода под разные ситуации, который заметно облегчает работу. Кроме того во многих проектах есть сложный функционал, который нужно где-то хранить. Я встречал подключение классов в init.php (как довольно грамотно сделанное с автолоадом, так и простые инклуды), всякие вычисления в result_modifier.php, сам я раньше создавал под проект свой специфический модуль. Однако же сейчас я остановился на создании универсального локального модуля, который уже содержит все наработки и готов к написанию специфичного функционала. На всех проектах я использую модуль «local.lib». Название через точку чтобы он отобразился в списке модулей marketplace. Что именно можно и нужно делать в модуле?

На текущий момент битрикс поддерживает автоматический автолоад классов. Тавтология небольшая, но тем не менее. Автолоад классов - подключение класса по требованию. Автоматический автолоад - не нужно прописывать классы в автолоад заранее, путь до файла автоматически определяется при вызове. Что это означает на практике? В папке с модулем создаете папку /lib/, в папке /lib/ создаете файл testecho.php, название обязательно в нижнем регистре. В файле пишете: