Основные свойства

• Работа с файлами XLS/XLSX/CSV.
• Поддержка PHP 7.4, 8.*
• Конфигурирование через файлы.
• Поддержка полей товаров miniShop2, включая опции категорий, производителя, галерею товара и т. д.
• Работа с MIGX-полями (настраиваемое форматирование).
• Поддержка контейнеров Collections.
• Возможность mSearch2-индексации импортированных ресурсов.
• Возможность пакетной загрузки.
• Возможность предварительного тестирования перед импортом.
• Сохранение резервной копии базы перед импортом и восстановление данных при необходимости.
• Системные события для плагинов.

Установка

Пакет устанавливается стандартным образом через установщик MODX. После установки в меню появится компонент «Impex».

Конфигурирование

Принцип конфигурирования схож с компонентом «Catalogfill» Андрея Чиркова. Конфигурации импорта/экспорта представляют собой php-файлы в директории {core_url}components/impex/config/.
В каждом файле должен присутствовать массив $impex_config со следующими ключами и значениями:

content_row

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

array('Название колонки', 'ID или имя поля в базе', 'Тип данных', array('поля MIGX')),

Например:

$impex_config['content_row'] = array(
    array('Категории',5,'categories'),
    array('Наименование','pagetitle','resource'),
    array('Артикул','article','ms'),
    array('Расширенный заголовок','longtitle','resource'),
    array('Краткое описание','introtext','resource'),
    array('Содержимое','content','resource'),
    array('Цена','price','ms'),
    array('Производитель','vendor','ms'),
    array('Новинка','new','ms'),
    array('Теги','tags','ms'),
    array('Цвет','color','ms'),
    array('Материал','material','msoption'),
    array('На складе',5,'tv'),
    array('Характеристики','chars','migx', array('title','value')),
    array('Галерея','images/import/','msgallery'),
    array('Дополнительные категории','','mscats'),
);

Поддерживаемые типы данных

categories

Категории ресурса. Вторым элементом массива указывается ID шаблона категории (5 в примере выше).
В импортируемом файле категории должны быть представлены в виде цепочки Категория 1||Категория 2||Категория 3, включая выбираемого при импорте/экспорте родителя.

Если в файле первой категорией указан «Каталог», а при импорте выбрать родителем иную категорию, система выдаст сообщение с предложением проверить файл.

При импорте скрипт проверит наличие на сайте категорий в соответствии с указанной цепочкой и создаст недостающие при их отсутствии с указанным шаблоном и классом ресурса (см. параметр category_class далее).

resource

Стандартные поля ресурса MODX — pagetitle, longtitle, published и т. д.

tv

TV-поле.Вторым элементом массива указывается имя поля или его ID (второе предпочтительнее — меньше запросов).

migx

TV-параметры типа MIGX. Второй элемент как и в случае с tv — имя поля или его ID. Третий — массив названий полей из конфигурации MIGX.

Например, у ресурса есть MIGX-TV с характеристиками под названием chars, в котором для каждого элемента существуют поля title и value
В этом случае запись конфига будет выглядеть так:

array('Характеристики','chars', 'migx', array('title','value')),

Если у ресурса в данном поле прописано, к примеру:

Материал = Хлопок
Цвет = Зелёный
Размер = XL

При экспорте данные будут записаны в файл в следующем виде:

Материал--Хлопок||Цвет--Зелёный||Размер--XL

При импорте эта строка будет сконвертирована обратно в JSON и записана в базу:

[
    {"MIGX_id":0,"title":"Материал","value":"Хлопок"},
    {"MIGX_id":1,"title":"Цвет","value":"Зелёный"},
    {"MIGX_id":2,"title":"Размер","value":"XL"}
]

Настройка разделителей между полями и значениями производится в параметре migx_separators (см. далее).

ms

Поля продукта miniShop2 (таблица modx_ms2_products): article, price, old_price, weight, vendor, tags, new и т. д.

Для множественных значений (теги, цвета, размеры) в импортируемом файле используйте разделитель ||: Тег01||Тег02||Тег03

Для производителя товаров miniShop2 vendor указывайте его название. Если такого производителя на сайте нет, он будет автоматически создан при импорте.

msoption

Опция товара (опции категорий). Для множественных значений в импортируемом файле используйте разделитель ||

msgallery

Галерея товара miniShop2.

В импортируемом файле пути к изображениям прописывайте через разделитель ||:

image01.jpg||image02.jpg||image03.jpg||image04.jpg||image05.jpg||image06.jpg

Изображения должны быть предварительно загружены в директорию-источник, которая указана (относительно корня сайта) вторым элементом массива:

array('Галерея','images/import/','msgallery'),

Если директорию не указывать:…

array('Галерея','','msgallery'),

… скрипт будет искать изображения в директории-источнике по умолчанию: {assets_url}components/impex/images/.

При экспорте данные берутся из таблицы modx_ms2_product_files. В файл сохраняются пути к основным изображениям, лежащим в корне директории продукта.

То есть, если для товара с ID=25 структура папок такая:

assets
  images
    products
      25
        small/
        webp/
        01.jpg
        02.jpg
        03.jpg

То в файл запишется: 25/01.jpg||25/02.jpg||25/03.jpg

При замене изображений товара (режим «Обновить всё», см. далее) можно, не меняя сам XLS/CSV-файл, просто создать необходимую структуру в любом месте, загрузить туда новые файлы:…

images
  import
    25
      01.jpg
      02.jpg
      03.jpg

… и указать в настройках данную директорию в качестве источника:

array('Галерея','images/import/','msgallery'),

mscats

Дополнительные категории товаров miniShop2 (вкладка «Категории» редактора товара в админке).
Указывается в виде ID категорий. Вторым элементом массива можно указать разделитель между значениями (если пусто, используется ||).
К примеру, если у товара указаны доп. категории 43, 48 и 56, то для такой настройки:…

array('Дополнительные категории','|','mscats'),

… в файле будет так: 43|48|56

Другие настройки

content_default

Значения по умолчанию при импорте и экспорте:

$impex_config['content_default'] = array(
    array('template',6), // ID шаблона ресурса
    array('published',1), // Опубликован
    array('show_in_tree',1), // Виден в дереве
);

Если значения не указаны ни тут, ни в основной разбивке колонок (а их, естественно, можно добавить в $impex_config['content_row'] напрямую: array('Публиковать','published','resource'),), скрипт проверит наличие системных настроек и настроек miniShop2 для товаров (шаблон товара, публикацию, видимость в дереве).

resource_class

Класс ресурса. Для товаров miniShop2 используйте msProduct, для стандартных ресурсов MODX — modResource.

category_class

Класс категории. Для категорий miniShop2 используйте msCategory, для стандартных ресурсов MODX — modResource и CollectionContainer для коллекций, если установлен компонент Collections.

chk_field

Поле, по которому ищется ресурс при импорте.
Указывается в формате

array('название поля', 'тип поля');

Если тип ms или tv, поиск идёт просто по значению (соответственно, они должны быть уникальными). Если используете resource (например, pagetitle), то ещё учитывается родитель.

Например, для товаров miniShop2 можно использовать артикул:

$impex_config['chk_field'] = array('article','ms');

include_captions

Идут ли первой строкой в файле названия полей true/false.

migx_separators

Разделители для MIGX-полей.
Первый элемент массива — разделитель между элементами, второй — между полями внутри элемента:

$impex_config['migx_separators'] = array('||','--');

Тут MIGX-TV, содержащее элементы, состоящие из полей image, title, text и link:…

array('Преимущества','benefits','migx',array('image','title','text','link')),

… запишется в файл в виде:

icons/icon01.svg--Низкие цены--Мы держим низкие цены--[[~15]]||icons/icon02.svg--Богатый опыт--У нас большой опыт--[[~16]]

batch_import

Количество товаров, обрабатываемых при импорте за один проход (0 — без ограничений). Уменьшите, если сервер не успевает обрабатывать указанное кол-во товаров за раз (актуально при включенной обработке галереи miniShop2).

alias_field

Какое поле использовать для генерации псевдонима при создании нового ресурса.
Если оставить пустым, псевдоним не генерируется (например, если в $impex_config['content_row'] прямо указываете alias:

array('Псевдоним','alias','resource'),

Экспорт ресурсов

Для экспорта достаточно выбрать родительский ресурс в дереве, конфигурацию (нажав кнопку рядом, можно открыть файл конфигурации и отредактировать его), тип файла и нажать «Экспорт». Ссылка на созданный файл будет выведена тут же.

Импорт ресурсов

Для импорта необходимо выбрать родительский ресурс, конфигурацию (также можно отредактировать), загрузить и/или выбрать файл для импорта из списка (можно удалить файлы при необходимости) а также выбрать режим обработки галереи miniShop2, предварительно загрузив изображения в указанную в $impex_config['content_row'] директорию-источник:

• «Не обрабатывать» — скрипт не будет учитывать изображения в файле.
• «Загружать только новые» — для новых товаров будут загружены новые изображения, для существующих товаров оставлены старые и добавлены новые, если они есть в файле и директории-источнике.
• «Обновить все» — для новых товаров будут загружены новые изображения, у существующих галерея сперва будет очищена, а потом загружены новые, указанные в файле, изображения.

Все операции производятся стандатными процессорами miniShop2 gallery/upload и gallery/removeall. Данные процессы достаточно ресурсоёмки, поэтому используйте обработку галереи в соответствии с мощностью вашего сервера.
После успешной обработки галереи все указанные в файле импорта исходники из директории-источника удаляются.

Дополнительно можно отметить опции:

• Тестирование. Если выбрано, после импорта откроется окно со ссылкой на системный журнал, где данные будут представлены в виде массива. Новые товары, данные, изменённые плагинами, а также новые категории будут помечены.
• Индексировать ли ресурс после импорта для компонента mSearch2, если он установлен в системе.
• Сохранять ли перед импортом резервную копию.

Если создание бэкапа включено, скрипт, прежде чем отправить данные на импорт, сохранит дамп контентных таблиц в директорию {assets_url/components/impex/backups/} и выведет ссылку на него.
Таблицы, сохраняемые в резервную копию (modx_ — префикс по умолчанию, у вас может быть иной):

• modx_site_content
• modx_site_tmplvar_contentvalues

Если установлен miniShop2, добавляются:

• modx_ms2_products
• modx_ms2_vendors
• modx_ms2_product_options
• modx_ms2_product_files
• modx_ms2_product_categories

Если установлен mSearch2 добавляются:

• modx_mse2_words
• modx_mse2_intro

Восстановление из резервной копии

На вкладке можно выбрать нужную резервную копию и восстановить данные из неё. Данный процесс необратим, так что будьте внимательны.

Системные события (события плагинов)

При установке пакета создаются четыре системных события:

OnImpexBeforeResourceExport

Вызывается перед экспортом ресурса. Доступные переменные:

$id - ID ресурса
$field - имя поля
$type - тип поля
$value - значение

Пример использования (присоединяет к заголовку страницы ее ID):

switch ($modx->event->name){
    case 'OnImpexBeforeResourceExport':
        if($field == 'pagetitle') $value = $value.'-'.$id;
        $modx->event->returnedValues['value'] = $value;
    break;
}

OnImpexBeforeResourceImport

Вызывается перед импортом ресурса. Доступные переменные такие же как при экспорте:

$id - ID ресурса
$field - имя поля
$type - тип поля
$value - значение

OnImpexAfterResourceImport

Вызывается после импорта ресурса. Доступен $id — ID импортированного ресурса. Пример использования:

switch ($modx->event->name){
    case 'OnImpexAfterResourceImport':
        if($resource = $modx->getObject('modResource', $id)){
            $resource->set('alias', 'resource-'.$id);
            $resource->save();
        }
    break;
}

OnImpexAterAllImport

Вызывается после импорта всех ресурсов. Доступен массив $ids — ID всех импортированных ресурсов. Пример использования:

switch ($modx->event->name){
    case 'OnImpexAterAllImport':
        foreach($ids as $id){
            if($resource = $modx->getObject('modResource', $id)){
                $resource->set('published', 1);
                $resource->save();
            }
        }
    break;
}

Запуск импорта по расписанию

Запуск удобнее осуществлять посредством компонента CronManager.

Для его работы нужно на сервере добавить CRON-задание для запуска скрипта {assets_url}/components/cronmanager/cron.php (подробности в документации).

При создании новой задачи в CronManager, выберите сниппет ImpexCRON, который идёт в комплекте с Impex, настройте расписание и укажите параметры запуска:

parent: 25
config: resource
file: import.xlsx
gallery: new

В данном случае в качестве родителя будет выбран ресурс с ID = 25, конфигурация resource.php, файл import.xlsx, который нужно предварительно загрузить в директорию {assets_url}/components/impex/files/ и режим обработки галереи miniShop3 (new — только новые, refresh — перезапись, если параметр не указывать, галерея не обрабатывается).