FAQ: Как отдавать обновления модулей через Центр обновлений¶

Это статья для разработчиков, которые предлагают модули для CS-Cart и Multi-Vendor и хотят упростить процесс обновления для своих пользователей. Вместо того, чтобы разрабатывать собственный механизм или просить клиентов вручную менять файлы, вы можете просто предложить им перейти в раздел Администрирование → Центр обновлений и получить обновления для модулей там.

Когда выпускать обновления модулей?¶

Есть две основные причины для выпуска обновления:

Вы разработали новую функциональность и готовы отдать её клиентам.

В ядре CS-Cart или Multi-Vendor произошли изменения:

удалены константы, классы, функции или хуки, которые используются вашим модулем;

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

константы, классы, функции или хуки, которые используются вашим модулем, помечены как устаревшие (deprecated). Мы не удаляем их сразу, но лучше переключиться на новую функциональность до того, как мы всё-таки удалим старую;

в базе данных изменилась структура таблиц, используемых модулем.

Это изменение не обязательно приведёт к поломке модуля — мы сохраняем обратную совместимость между релизами CS-Cart. Но если модуль использует прямые запросы к таблицам вместо функций ядра, то модуль может перестать работать.

Примерно в то же время, когда мы выпускаем новую версию CS-Cart/Multi-Vendor, мы также анонсируем изменения ядра в специальном разделе документации для разработчиков .

Куда загружать пакеты обновлений?¶

Если хотите, чтобы покупатели могли обновить модуль через Центр обновлений, то есть два способа:

CS-Cart Marketplace. Там есть все необходимые инструменты для сборки и распространения обновлений . Пока эти инструменты в закрытом бета-тестировании; чтобы получить доступ, напишите нам на marketplace @ cs-cart . com.
Собственный сервер обновлений. Он нужен, если вы используете собственный механизм лицензирования и раздачи пакетов обновлений. Такой подход потребует от вас специальным образом подготовить модуль и самостоятельно собирать пакеты обновлений. Инструкции есть дальше в статье.

Как сделать модуль совместимым только с определёнными версиями CS-Cart?¶

Требования в файле addon.xml проверяются только в процессе установке модуля . Они НЕ проверяются при обновлении.

Если после обновления требования модуля поменялись, то недостаточно поменять addon.xml. Чтобы клиенты не установили обновление, которое не будет работать с их версией, у вас есть два варианта:

передавайте версию CS-Cart/Multi-Vendor на ваш сервер обновлений , и пусть сервер решает, предлагать ли обновление;
добавьте в пакет обновления валидатор , и пусть он не даёт установить обновление, если не выполнены определённые требования.

Как подготовить модуль к работе с Центром обновлений?¶

CS-Cart и Multi-Vendor проверяют наличие обновлений в 2 случаях:

Когда кто-то заходит в панель администратора (но только если в Настройки → Общие включена настройка Проверять наличие обновлений автоматически).
Когда кто-то заходит в Администрирование → Центр обновлений.

Вот несколько вещей, которые нужно учесть при адаптации модуля для работы с Центром обновлений:

Чтобы проверять наличие обновлений и скачивать их, в модуле должен быть коннектор Центра обновлений. Этот коннектор — класс, который должен быть размещен в app/addons/[sample_addon]/Tygh/UpgradeCenter/Connectors/[SampleAddon]/Connector.php, где
- [sample_addon] — идентификатор модуля;
- [SampleAddon] — идентификатор модуля, записанный в CamelCase.
Вот пример коннектора с комментариями:

Как подготовить пакет обновлений?¶
Основная информация¶
Для сборки пакета обновлений нужны два архива: со старой и новой версиями модуля. Чтобы собрать пакет обновлений, используйте следующие команды из нашего SDK:

Чтобы собирать обновления c помощью SDK, придерживайтесь следующей структуры модуля при разработке:

[sample_addon] — идентификатор модуля;

[SampleAddon] — идентификатор модуля в CamelCase;

[version1] — номер версии, например 1.1.0.

[version2] — номер версии, например 1.1.1.

app/addons/[sample_addon]/upgrades/[version]/migrations — папка с миграциями, которые надо применить при обновлении до [version].

app/addons/[sample_addon]/upgrades/[version]/validators — папка с валидаторами, которые должны выполнить свои проверки перед обновлением до [version].

app/addons/[sample_addon]/upgrades/[version]/scripts — папка с pre/post-скриптами, которые нужно выполнить перед или после обновления до [version].

app/addons/[sample_addon]/upgrades/[version]/extra_files — папка с дополнительными файлами, которые используются только в процессе обновления и не добавляются в установку CS-Cart/Multi-Vendor.

app/addons/[sample_addon]/upgrades/[version]/extra/extra.php — файл для расширения package.json пакета обновлений.

Файлы и папки в app/addons/[sample_addon]/upgrades/[version] не обязательны. Например, если у новой версии нет изменений в базе данных, то нет необходимости создавать папку с миграциями.
Миграции¶
Миграции применяются во время обновления и меняют структуру таблиц в базе данных и сами данные в них.

Для написания миграций используйте Phinx. Обратите внимание, что в CS-Cart старая версия Phinx (0.4.3), поэтому не все инструкции из современной документации могут подойти. Вот старая документация Phinx 0.4.3 о:

Класс миграции должен содержать метод up , который будет выполняться в процессе обновления.

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

Не переименовывайте сгенерированные в формате YYYYMMDDHHMMSS_my_new_migration.php миграции. В случае, если вы пишете миграции вручную, присваивайте им имена согласно правилам Phinx.

Не используйте чистый SQL в миграциях для изменения структуры таблицы; используйте только методы Phinx.

Не используйте функции ядра CS-Cart в миграциях: нет гарантии, что они будут доступны во время обновления модуля. В результате процесс обновления может прерваться, а магазин — сломаться.
Валидаторы¶
Валидаторы проверяют перед установкой обновления, соответствует ли магазин определённым требованиям. Каждый валидатор — отдельный класс в пространстве имён Tygh\UpgradeCenter\Validators .

Валидатор должен реализовывать интерфейс IValidator и содержать 2 обязательных метода:
- getName() должен возвращать строку с отображаемым именем валидатора;
- check($schema, $request) должен возвращать массив с двумя значениями:
  - флаг (boolean), который означает, что проверка успешно пройдена;
  - строка (string) с сообщением, которое отобразится, если результат проверки будет неудачным.
  Скрипты¶
  Скрипты расширяют или меняют то, как Центр обновлений работает с вашим пакетом обновлений при обновлении. Есть 2 типа скриптов:
  
  перед обновлением: скрипт pre_script.php выполняется после того, как прошли все проверки валидаторов;
  
  после обновления: скрипт post_script.php выполняется после того, как установлен пакет обновлений. Пост-скрипт в основном используется для того, чтобы показывать какие-то уведомления после обновления. Чтобы сделать такое уведомление, добавьте новый элемент в массив $upgrade_notes в скрипте:
  
  Эти скрипты включены в контекст класса \Tygh\UpgradeCenter\App и могут использовать все свойства и методы этого класса. Также вы можете в них использовать все функции и классы CS-Cart.
  Папка Extra Files¶
  В папку extra_files вы можете положить файлы, которые используются только при обновлении и не добавляются в установку CS-Cart/Multi-Vendor.
  Расширение схемы пакета обновлений¶
  Чтобы расширить схему, напишите свой скрипт в файле extra.php. Скрипт должен возвращать массив. Этот массив сольётся с package.json пакета обновлений.
  
  Так вы можете добавлять любые дополнительные данные в пакет обновлений. Эти данные можно использовать в процессе обновления в пре- и пост-скриптах.
  
  Например, вот как можно предложить клиентам пропустить встроенное в CS-Cart резервное копирование при установке обновления:
  
  Как настроить собственный сервер обновлений?¶
  
  Свой сервер обновлений настраивать необязательно — есть и другой путь . Но если ваши модули используют свой механизм лицензирования, то стоит завести свой сервер обновлений.
  
  Когда CS-Cart отправляет запрос о наличии обновлений, сервер обновлений должен вернуть XML следующего вида:
  
  update/packages/item содержит в себе информацию о доступном обновлении;
  
  update/packages/item@id — уникальный идентификатор пакета обновлений. Когда коннектор передаёт этот идентификатор серверу обновлений, то сервер должен предоставить архив с пакетом обновлений;
  
  update/packages/item/file — название архива с пакетом обновлений;
  
  update/packages/item/name — заголовок пакета обновлений (отобразится в Центре обновлений);
  
  update/packages/item/description — описание пакета обновлений. Может содержать HTML-разметку;
  
  update/packages/item/from_version — текущая версия модуля;
  
  update/packages/item/to_version — версия, до которой будет обновлен модуль;
  
  update/packages/item/timestamp — дата создания пакета обновлений в формате UNIX timestamp;
  📎📎📎📎📎📎📎📎📎📎

FAQ: Как отдавать обновления модулей через Центр обновлений¶

Когда выпускать обновления модулей?¶

Куда загружать пакеты обновлений?¶

Как сделать модуль совместимым только с определёнными версиями CS-Cart?¶

Как подготовить модуль к работе с Центром обновлений?¶

Как подготовить пакет обновлений?¶

Как настроить собственный сервер обновлений?¶