Перейти к содержимому
BXWiki

Свой модуль не устанавливается - разбор причин

Модуль не появляется в списке установки или его установка обрывается на середине. Разбираем причины по убыванию частоты, начиная с описания модуля.

С чего начать

Проверяем обязательный минимум описания:

Окно терминала
ls -la /home/bitrix/www/local/modules/vendor.module/install/
grep -n 'MODULE_ID\|PARTNER_NAME\|class ' /home/bitrix/www/local/modules/vendor.module/install/index.php | head
cat /home/bitrix/www/local/modules/vendor.module/install/version.php
# без версии, кода модуля и имени партнёра решение считается некорректным

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

Сверяем имя класса с кодом модуля:

/local/modules/vendor.module/install/index.php
class vendor_module extends CModule    // точки в коде заменяются подчёркиваниями
{
    public $MODULE_ID = 'vendor.module';
}
// имя класса не совпало с кодом - методы установки просто не вызовутся

Платформа ищет класс по имени, собранному из кода модуля. Несовпадение выглядит как молчание: модуль в списке есть, а установка ничего не делает.

Ищем скрытые файлы после переноса:

Окно терминала
find /home/bitrix/www/local/modules/vendor.module -name '.*' -maxdepth 3 | head
ls -la /home/bitrix/www/local/modules/vendor.module/install/components/*/*/ | head
# файлы .description.php и .parameters.php обязаны быть на месте

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

Проверяем сохранение настроек модуля:

// options.php: блок сохранения идёт ДО вывода формы
if ($request->isPost() && $request['save'] && check_bitrix_sessid()) {
        Option::set('vendor.module', 'api_key', (string)$request['api_key']);
}
// без проверки ключа сессии сохранение молча не срабатывает

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

Причины

  1. Описание модуля неполное примерно 30% случаев

    ПризнакРешение не принимается вовсе: сообщение о неверном содержимом архива или пустой список установки.

    ПроверкаСмотрим файл версии и обязательные значения в описании: код модуля, имя и адрес партнёра.

    Что делатьЗаполняем все обязательные значения: проверка идёт по ним до запуска кода установки.

  2. Имя класса не совпадает с кодом модуля примерно 25% случаев

    ПризнакМодуль в списке есть, кнопка установки работает, но ничего не происходит.

    ПроверкаСравниваем имя класса в описании с кодом модуля: точки заменяются подчёркиваниями.

    Что делатьПриводим имя класса к коду модуля и наследуемся от базового класса без ведущего слеша.

  3. Потерялись файлы, начинающиеся с точки примерно 20% случаев

    ПризнакУстановка обрывается на регистрации компонентов или компоненты не появляются.

    ПроверкаИщем в каталоге модуля файлы описания компонентов и параметров.

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

  4. Тексты захардкожены мимо языковых файлов примерно 15% случаев

    ПризнакУстановка проходит, но русский текст в интерфейсе выглядит нечитаемым.

    ПроверкаИщем строки на русском прямо в коде модуля вместо обращения к языковым сообщениям.

    Что делатьВыносим тексты в языковые файлы: перекодировка при установке применяется только к ним.

  5. Обновление зовёт код, которого ещё нет примерно 10% случаев

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

    ПроверкаСмотрим файл обновления: он вызывает API самого обновления, ещё не подключённого на этом запросе.

    Что делатьДелаем код обновления независимым от нового API и безопасным для повторного запуска.

Частые вопросы

Где должен лежать свой модуль?

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

Почему настройки модуля не сохраняются?

Блок сохранения стоит после вывода формы или не проверяет одноразовый ключ сессии. Сохранение размещают до формы и с обязательной проверкой ключа.

Почему не работает переход к настройкам модуля?

В административном скрипте не объявлено имя модуля. Без него платформа не знает, к какому модулю относится страница.

Нужно ли проверять результат подключения модуля?

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

Как проверить установку до передачи заказчику?

Развернуть модуль на чистой копии сайта и пройти установку и удаление целиком. Установка на своём стенде, где файлы уже лежат, ничего не проверяет.

Смежное

Первоисточник