Упаковка модуля/решения в архив

Правильно собранный архив — половина успешной модерации в Маркетплейс. Разберём структуру каталога, что включать и что исключать, как оформить description.php, задать версию и проверить установку на чистой копии.

Структура каталога решения

Дистрибутив тиражного решения — это не «просто папка модуля», а собранный по правилам каталог, который партнёрский кабинет принимает как единое целое. В основе лежит символьный код модуля вида partner_code.module_name, где префикс — код партнёра, а суффикс — имя решения. Все системные каталоги и файлы располагаются относительно этого имени.

Минимальный набор для решения-модуля обычно выглядит так:

• install/ — установщик модуля (install/index.php, install/version.php, при необходимости install/db/, install/components/, install/updater/);
• lib/, classes/, lang/ — код и языковые файлы модуля;
• description.php — описание решения для витрины и мастера установки;
• каталог со скриншотами и картинками (например images/).

Файл description.php

Файл description.php описывает решение для витрины Маркетплейс и мастера установки. В нём задаются заголовок, описание, набор картинок и параметры совместимости. Технически это PHP-файл, который заполняет массив описания решения — его читает система при выкладке и установке.

Проверьте перед сборкой:

• корректный заголовок и описание без «битых» символов;
• список скриншотов, реально присутствующих в архиве;
• указание совместимых редакций и версий, если это применимо к вашему решению.

Версия в version.php

Версия решения хранится в install/version.php. Это единая точка правды для системы обновлений и для кабинета партнёра. Формат строго определён:

<?php $arModuleVersion = array("VERSION" => "1.0.1", "VERSION_DATE" => "2026-01-01 00:00:00");

Правила, которые экономят часы отладки:

• VERSION должна расти по возрастанию (1.0.0 → 1.0.1 → 1.1.0) — от этого зависит применение обновлений;
• VERSION_DATE — дата в формате Y-m-d H:i:s, не из будущего;
• версия в архиве и версия, указанная в кабинете при загрузке, должны совпадать.

Что включать и что исключать

Чистота архива — это не косметика: лишние файлы раздувают дистрибутив, тянут за собой чужие настройки окружения и почти гарантированно вызывают вопросы на модерации. Разделите содержимое на «в архив» и «мимо архива».

Пошаговый чек-лист сборки

Стабильный результат даёт повторяемая процедура. Проходите её каждый раз перед загрузкой в кабинет партнёра:

1. Обновите VERSION и VERSION_DATE в install/version.php.
2. Проверьте, что install/index.php содержит методы DoInstall(), DoUninstall(), InstallDB(), UnInstallDB(), InstallEvents(), InstallFiles() в согласованном виде.
3. Актуализируйте description.php и список скриншотов.
4. Уберите служебные каталоги и файлы (см. таблицу выше).
5. Проверьте кодировку и права (следующие разделы).
6. Соберите архив с корнем на каталоге модуля.
7. Установите решение на чистой копии и убедитесь, что удаление проходит без ошибок.

Права на файлы и кодировка

Два параметра ломают установку чаще всего — кодировка и права доступа. Их проще проверить заранее, чем ловить по логу на стороне клиента.

• Кодировка. Ориентируйтесь на кодировку целевой редакции продукта: как правило это UTF-8 без BOM. BOM в начале PHP-файла вызывает предупреждения «headers already sent» при установке.
• Права. Каталоги обычно 0755, файлы 0644. Исполняемые биты и «мировая» запись (0777) недопустимы.
• Переносы строк. Приводите к LF, чтобы избежать «грязных» диффов и предупреждений парсера.

Проверка установки на чистой копии

Финальный контроль — установка собранного архива на «чистый» стенд, где вашего модуля никогда не было. Локальные кэши и остатки предыдущих версий на рабочей машине маскируют ошибки, которые проявятся у клиента.

Что проверить на чистом стенде:

• решение появляется в списке и корректно устанавливается через мастер;
• создаются нужные таблицы (InstallDB) и регистрируются обработчики событий (InstallEvents);
• копируются публичные файлы и компоненты (InstallFiles);
• полное удаление через DoUninstall() не оставляет «хвостов» и не роняет сайт.

Отдельно прогоните сценарий «установка → удаление → повторная установка» — он вскрывает проблемы неидемпотентных операций в установщике.

Итог

Качественный дистрибутив тиражного решения — это точное имя модуля, корректный install/version.php, аккуратный description.php, чистая структура без служебных файлов, выверенные кодировка и права, и обязательная проверка полного цикла установки и удаления на чистой копии. Такой архив проходит модерацию быстрее и не создаёт проблем клиентам.

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