Папка /local/. Практическое руководство по структурированию, переносу и настройке проектов

1С-Битрикс — это мощная CMS, широко используемая для создания корпоративных сайтов, интернет-магазинов и других веб-ресурсов. С внедрением архитектуры D7 и добавлением папки `/local` разработчики получили удобное средство для управления пользовательскими доработками, изоляции их от системных файлов и повышения гибкости в процессе разработки. В этой статье мы подробно разберем, как правильно использовать папку `/local` для организации кода, переноса старого проекта и создания эффективной структуры файлов.

Зачем нужна папка /local?

С введением папки `/local` в 1С-Битрикс с версии D7 (начиная с релиза 14.0.1) разработчики получили возможность изолировать пользовательский код от стандартных системных файлов. Это нововведение значительно упрощает обновления ядра системы, так как все изменения находятся в одном месте и не пересекаются с файлами ядра.

Основные преимущества использования папки `/local`:

• Упрощение обновлений системы. Все изменения и кастомизации хранятся отдельно от системных файлов в `/bitrix`, что минимизирует риски потери данных при обновлениях.
• Безопасность и изоляция. Пользовательский код не мешает работе самой системы, и обновления системы могут происходить без влияния на изменения в проекте.
• Упорядочение кода. Благодаря разделению кода по папкам становится проще ориентироваться и управлять проектом.

Структура папки /local и описание её содержимого

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

1. /local/activities — Действия для бизнес-процессов (БП)

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

Пример:

/local/activities/SendEmail.php

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

2. /local/components — Компоненты

Здесь хранятся как пользовательские компоненты, так и переопределенные стандартные компоненты 1С-Битрикс. Компоненты — это блоки функционала, которые можно многократно использовать на сайте, такие как формы, списки, галереи и т. д.

Пример:

/local/components/my_component/detail.php

Если вам нужно изменить внешний вид стандартного компонента, вы можете просто скопировать его в `/local/components/`, внести необходимые изменения, и он будет работать, не затрагивая оригинальный код в `/bitrix`.

3. /local/gadgets — Гаджеты для рабочего стола

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

Пример:

/local/gadgets/dashboardWidget.php

4. /local/modules — Самописные модули

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

Пример:

/local/modules/my_module/include.php

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

5. /local/php_interface — Файлы настройки системы

Это одна из важнейших папок в проекте. Здесь содержатся все скрипты, которые отвечают за настройку и кастомизацию работы Битрикс. В этой папке обычно размещаются:

• init.php — файл инициализации, где подключаются все необходимые компоненты, классы и модули.
• events.php — обработчики событий, которые добавляют собственную логику в стандартные процессы.
• constants.php — файл с константами, которые могут использоваться в проекте.

Пример структуры:

/local/php_interface/
  init.php
  events.php
  constants.php
  classes/
    User.php

init.php — подключает все файлы, включая `events.php`, `constants.php`, а также регистрирует автозагрузку классов.

Пример автозагрузчика:

spl_autoload_register(function ($className) {
    $classPath = __DIR__ . '/classes/';
    $fileName = $classPath . str_replace('\\', '/', $className) . '.php';

    if (file_exists($fileName)) {
        require_once $fileName;
    }
});

events.php — обрабатывает события системы, например, создание новых пользователей, обновление данных и другие важные операции.

6. /local/templates — Шаблоны сайта

Эта папка содержит все кастомные шаблоны для вашего сайта. Здесь могут храниться как основные шаблоны сайта, так и шаблоны отдельных компонентов.

Пример:

/local/templates/my_template/header.php

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

7. /local/blocks — Блоки и элементы для верстки

Для удобства и согласованности стилей в проекте можно использовать блоки, как в подходе БЭМ. В папке `/local/blocks` можно организовать код по принципу переиспользуемых блоков. Это может быть полезно для создания модульных элементов интерфейса.

Пример:

/local/blocks/button/button.css
/local/blocks/form/form.js

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

8. /local/routes — Конфигурация маршрутов

Если в проекте используется роутинг (например, для REST API или кастомных маршрутов для страниц), то все настройки маршрутов и их обработчиков размещаются в этой папке.

Пример:

/local/routes/apiRoutes.php

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

9. /local/js — JavaScript и сторонние библиотеки

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

Пример:

/local/js/jquery.min.js
/local/js/myCustomScript.js

10. /local/images — Изображения и файлы для шаблонов

Все изображения для шаблонов, шрифты или прочие статические файлы, которые не имеют отношения к функционалу, можно хранить в папке `/local/images`. Это обеспечит чистоту структуры и удобство работы с ресурсами.

Пример:

/local/images/logo.png

Как переносить старый проект в /local

Если вам нужно перенести старый проект, в котором уже есть доработки в `/bitrix`, то вам предстоит следовать несколько шагов:

1. Использование Монитора качества

Сначала запустите Монитор качества в панели управления Битрикс. Это позволит вам понять, какие файлы были изменены в системе, и какие из них следует перенести в `/local`.

2. Создание и настройка папки /local

Создайте структуру в папке `/local`, как указано выше. Для начала вам нужно будет создать файлы и папки для работы: `init.php`, `events.php`, `constants.php`, а также скрипты для автозагрузки классов.

3. Перенос шаблонов и компонентов

Все изменённые шаблоны и компоненты нужно перенести в соответствующие папки в `/local`. Например, из `/bitrix/templates/.default` в `/local/templates/.default` или создать новый шаблон, который будет расширять существующий.

4. Проверка путей и ссылок

После того как вы перенесли все файлы, проверьте пути к файлам. Замените все прямые ссылки на `/bitrix/` на `/local/`. Это особенно важно для шаблонов и компонентов, чтобы система корректно подхватывала файлы из новой папки.

5. Тестирование

После переноса всех файлов протестируйте проект. Убедитесь, что сайт работает корректно, и что все изменения из `/local` правильно подгружаются и функционируют.

Заключение

Папка `/local` в 1С-Битрикс — это мощный инструмент для организации пользовательского кода, управления проектом и повышения гибкости разработки. Разделение системных и пользовательских файлов, правильное структурирование папок и файлов внутри `/local` позволяет легче поддерживать проект, проводить обновления и интегрировать новые решения.

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