Как добавить код в 1С-Битрикс: практическое руководство

«1С-Битрикс: Управление сайтом» — это CMS на PHP, и добавить в неё код можно несколькими принципиально разными способами: от простой вставки HTML в текст страницы до написания собственных обработчиков событий и модулей. Выбор способа зависит от задачи: подключить счётчик метрики, изменить вывод компонента, добавить бизнес-логику при сохранении элемента или расширить API.

Главное правило безопасной разработки в Битриксе — никогда не править файлы ядра в папке /bitrix/modules/. При обновлении системы все изменения будут перезаписаны, а сайт может перестать работать. Весь пользовательский код размещается в шаблонах, файле init.php, папке /local/ или в собственных модулях.

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

Определяем, куда именно нужно добавить код

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

Отдельная ситуация — простой HTML или текст на конкретной странице. Его добавляют прямо через визуальный редактор в админке, без правки файлов. Но PHP-код через визуальный редактор вставлять нельзя: он не выполнится или будет экранирован.

Маршрут решения

Как выбрать точку подключения кода

Нужно вставить счётчик, виджет или метатег на все страницыПравьте header.php или footer.php шаблона сайта

Нужно изменить вывод конкретного компонента (каталог, новости)Копируйте и правьте шаблон компонента в шаблоне сайта

Код должен срабатывать при событии (заказ, регистрация, сохранение элемента)Добавьте обработчик события в init.php

Нужна переиспользуемая логика с настройками в админкеСоздайте собственный компонент или модуль

Добавляем код в шаблон сайта

Шаблон сайта находится в папке /bitrix/templates/имя_шаблона/ или, в современных проектах, /local/templates/имя_шаблона/. Ключевые файлы — header.php (шапка, открывающие теги, подключение стилей и скриптов) и footer.php (подвал, закрывающие теги). Код, вставленный сюда, выполнится на каждой странице, использующей этот шаблон.

Отредактировать файлы можно через административный раздел: «Настройки → Настройки продукта → Сайты → Шаблоны сайта» либо через «Контент → Структура сайта → Файлы и папки». Удобнее и безопаснее работать по FTP/SSH в файловом менеджере или IDE — так проще откатить изменение и есть подсветка синтаксиса.

Для подключения стилей и скриптов внутри шаблона используйте API Битрикса, а не прямые теги: методы $APPLICATION->SetAdditionalCSS() и $APPLICATION->AddHeadScript() корректно работают с механизмом объединения и кэширования файлов. Строковые вставки вроде счётчиков размещают перед закрывающим тегом </body> в footer.php.

<?php
// В header.php шаблона сайта
$APPLICATION->AddHeadScript(SITE_TEMPLATE_PATH . '/js/custom.js');
?>

Изменяем вывод через шаблон компонента

Большинство блоков на странице (каталог, корзина, формы, новости) выводится компонентами. Чтобы изменить их внешний вид или добавить свой код, шаблон компонента копируют в папку шаблона сайта. В админке это делается из режима правки: наведите на блок, выберите редактирование шаблона компонента — система предложит скопировать шаблон.

Скопированный шаблон попадает в /local/templates/имя_шаблона/components/пространство/компонент/имя_шаблона/. Внутри обычно есть файлы template.php (вывод), result_modifier.php (изменение массива результатов перед выводом) и component_epilog.php (код, выполняемый после вывода, работает даже при кэшировании).

Добавляйте PHP-логику преимущественно в result_modifier.php, а в template.php оставляйте только вывод. Так код легче читать и поддерживать. Помните: при кэшировании компонента код template.php может не выполняться при каждом хите — динамические данные выводите через component_epilog.php или отключайте кэш компонента.

Пишем код в init.php и обработчиках событий

Файл init.php выполняется при каждом запросе к сайту после инициализации ядра. Традиционно он лежит в /bitrix/php_interface/init.php, но рекомендуемое расположение — /local/php_interface/init.php: папка /local/ полностью отведена под пользовательский код и не затрагивается обновлениями.

Через init.php подключают обработчики событий — функции, которые ядро вызывает при определённых действиях: добавлении элемента инфоблока, оформлении заказа, регистрации пользователя. Обработчик регистрируется функцией AddEventHandler() или методом событийной модели D7.

<?php
// /local/php_interface/init.php
AddEventHandler("iblock", "OnAfterIBlockElementAdd", function(&$arFields) {
// Действия после добавления элемента инфоблока
// Например, запись в лог или отправка уведомления
});
?>

Не размещайте в init.php тяжёлые операции и вывод данных: файл выполняется при каждом хите, включая AJAX и административные запросы. Ошибка синтаксиса в init.php полностью остановит сайт — после правки сразу проверьте работоспособность главной страницы и админки.

Создаём собственный компонент или модуль

Когда код нужен в нескольких местах, должен иметь настройки в админке или подключаться через визуальный редактор, его оформляют как собственный компонент. Компонент размещается в /local/components/пространство/имя/ и состоит минимум из файла class.php (или component.php) и шаблона. После создания компонент появляется в дереве компонентов визуального редактора.

Для большой функциональности с собственными таблицами, страницами в админке и обработчиками создают модуль в /local/modules/идентификатор/. Разработка модуля требует понимания архитектуры Битрикса: установочные файлы, описание версий, регистрация в системе. Это работа для разработчика, а не для контент-менеджера.

Простой промежуточный вариант — подключение PHP-файла через компонент «Вставка включаемой области» или прямой вызов $APPLICATION->IncludeFile(). Так можно выполнить свой скрипт на отдельной странице, не создавая полноценный компонент.

1. 1
   Сделайте резервную копию файлов и базы или подготовьте тестовую копию сайта
2. 2
   Определите точку подключения: шаблон сайта, шаблон компонента, init.php или отдельный компонент
3. 3
   Внесите код в папку /local/ или в шаблон сайта, не трогая ядро
4. 4
   Проверьте работу страницы, админки и связанных сценариев (заказ, формы)
5. 5
   Очистите кэш Битрикса и браузера, если изменения не видны

Проверяем результат и очищаем кэш

Битрикс агрессивно кэширует компоненты и страницы, поэтому после правки кода изменения могут не отображаться. Очистите кэш в админке: «Настройки → Настройки продукта → Автокэширование» или кнопка очистки кэша на панели управления. Также проверьте, не включён ли композитный режим — при нём HTML страниц отдаётся из статики.

Проверяйте не только внешний вид, но и логи. Ошибки PHP смотрите в логе веб-сервера или в файле, заданном директивой error_log. Для отладки на тестовой копии можно включить вывод ошибок в файле .settings.php через параметр debug в секции exception_handling. На боевом сайте вывод ошибок посетителям включать нельзя — это риск раскрытия путей и служебных данных.

Контрольные точки

Как проверить результат

Отображение изменений на странице

Норма

Код выполняется, вывод соответствует задуманному после очистки кэша

Тревожный признак

Старая версия страницы — не очищен кэш или включён композитный режим

Работа административного раздела

Норма

Админка открывается, страницы редактируются

Тревожный признак

Ошибка 500 или белый экран — синтаксическая ошибка в подключённом коде

Лог ошибок PHP

Норма

Нет новых записей после обращения к странице

Тревожный признак

Fatal error или Warning с указанием на ваш файл

Типичные ошибки при добавлении кода

Самая частая ошибка — правка файлов ядра. Второе место занимает синтаксическая ошибка в init.php, из-за которой падает весь сайт. Третья группа проблем — код, конфликтующий с кэшированием: разработчик не понимает, почему его изменения «не работают», хотя дело только в закэшированном шаблоне.

Отдельно отметим безопасность: не выполняйте код из непроверенных источников, не передавайте данные из $_REQUEST напрямую в запросы к базе и не храните пароли в файлах шаблонов. SQL-инъекция или вредоносный скрипт в шаблоне даёт атакующему доступ ко всему сайту.

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

Можно ли добавить PHP-код прямо через визуальный редактор страницы?

Нет. Визуальный редактор предназначен для HTML-контента: PHP-код в нём не выполнится и будет показан как текст или удалён при сохранении. Для PHP используйте включаемые области с вызовом файла, шаблоны компонентов или правку файлов шаблона.

Где правильно размещать init.php — в /bitrix/ или в /local/?

Предпочтительно /local/php_interface/init.php. Папка /local/ целиком отведена под пользовательский код и не затрагивается обновлениями системы. Если файл существует в обоих местах, учитывайте порядок подключения и избегайте дублирования обработчиков.

Почему после правки шаблона изменения не видны на сайте?

Чаще всего виноват кэш: очистите кэш компонентов и страниц в админке, проверьте композитный режим и кэш браузера. Также убедитесь, что правите именно тот шаблон, который назначен сайту, — на одной установке может быть несколько шаблонов.

Как откатить изменения, если сайт сломался?

Если есть доступ по FTP или SSH, переименуйте или удалите проблемный файл — при ошибке в init.php сайт сразу восстановится. Затем верните исходную версию из резервной копии. Именно поэтому правки без копии на боевом сайте недопустимы.

Чем собственный компонент лучше вставки кода в шаблон?

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

Нужно ли знать PHP, чтобы добавить код в Битрикс?

Для вставки готовых HTML-фрагментов и счётчиков достаточно базового понимания разметки. Для обработчиков событий, шаблонов компонентов и модулей нужен PHP и знакомство с API Битрикса — без этого велик риск остановить сайт или создать уязвимость.