Транспортные пакеты

Что такое Транспортный пакет?¶

Транспортный пакет (далее ТП) - это набор объектов и файлов, которые можно использовать для "переноса" данных из одной установки MODX в другую; или даже для транспортировки сторонних компонентов в простом, легко управляемом формате. Другими словами, ТП могут транспортировать практически все - от данных базы данных, файлов и даже сценариев до запуска во время установки.

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

packagename-version-release.transport.zip

Примером ТП может быть myextra-1.0-rc1.transport.zip. Если бы вы загрузили myextra-1.0-rc2.transport.zip, MODX интерпретировал бы его как часть того же 'пакета', но его более новую версию. Поэтому он будет вести себя в режиме "обновления".

ТП хранятся в файлах .zip, оканчивающихся на .transport.zip. Их можно загрузить и установить везде, где есть MODX Revolution - независимо от конфигурации сервера.

Содержимое Транспортного пакета¶

MODX Revolution автоматически "распаковывает" ваши ТП. После этого в вашем каталоге core/packages появится подкаталог с именем zip-файла (без суффикса transport.zip). Этот подкаталог будет содержать:

• Файл manifest.php
• Поддиректории каждого Транспортного контейнера (подробнее об этом позже)

Он также может содержать файл saved.php, если пакет является обновлением предыдущего пакета, который содержит метаданные для восстанавливаемой установки. И, наконец, может быть файл setup-options.php, если пакет упакован внутри.

Файл манифеста manifest.php¶

В файле-манифесте обычно хранится вся необходимая информация для пакета, включая расположение файлов и информацию о них. Если вы откроете файл manifest.php, вы увидите, что он содержит возвращаемый гигантский массив PHP. В нем есть несколько ключей, которые могут вас заинтересовать:

• manifest-version - это говорит нам, какой версии является определение манифеста. MODX использует его, чтобы определить, как интерпретировать манифест и упростить для будущих версий MODX обратную совместимость.

• manifest-attributes - это любые настраиваемые атрибуты, которые были установлены в пакете при его сборке. Наиболее распространенными являются 'license', 'readme' и 'setup-options' которые MODX интерпретирует во время установки.

• manifest-vehicles - это метаданные Контейнера ТП в формате массива.

Хорошо, а что такое Контейнер транспортного пакета?¶

Транспортные Контейнеры (или Контейнеры Транспортного пакета) являются частью ТП. Пакет может содержать сколько угодно Транспортных Контейнеров, они также бывают разных типов; в настоящее время доступны:

• xPDOObjectVehicle - Для передачи данных базы данных
• xPDOFileVehicle - Для транспортировки файлов

В массиве "manifest-vehicles" вы увидите эти ключи для каждого Контейнера:

• vehicle_package - это говорит нам, какой тип пакета содержит эти Контейнеры. В настоящее время единственный вид - «transport».
• vehicle_class - имя класса данного типа Контейнера.
• class - имя класса транспортируемого объекта БД или xPDOFileVehicle, если это файловый Контейнер.
• guid - GUID, сгенерированный случайным образом для Контейнера.
• native_key - Если Контейнер является объектом базы данных, это будет его первичный ключ, по которому он будет идентифицирован.
• имя_файла - где в папке транспортного пакета находится исходный файл Контейнера.
• namespace - Некоторые пакеты используют поле namespace для группировки Контейнеров и других объектов, чтобы сделать их однозначно идентифицируемыми в установке MODX.

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

Внутри транспортного Контейнера¶

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

Опять же, это похоже на большой массив PHP с похожими ключами. Тем не менее, у него есть несколько дополнительных ключей, которые важны. xPDOFileVehicle и xPDOObjectVehicle могут иметь разные ключи. Давайте рассмотрим самые распространенные:

• class - аналогично манифесту, тип класса Контейнера.
• object - массив, содержащий информацию об объекте. Для объектов БД это, скорее всего, будет представление таблицы БД в виде массива JSON. Для файлов это будет массив PHP с источником, целью и названием Контейнера.
• vehicle_class - аналогично манифесту, имя класса Контейнера.
• ** vehicle_package** - аналогично манифесту, тип транспорта Контейнера.
• guid - аналогично манифесту, уникальный идентификатор Контейнера.
• package - Применимо только к xPDOObjectVehicles, скорее всего, это будет 'modx' или пусто.
• signature - подпись имени файла для этого Контейнера.
• native_key - аналогично манифесту. Если Контейнер является объектом базы данных, это будет его первичный ключ, по которому он будет идентифицирован.

XPDOObjectVehicle или Контейнеры с базой данных часто имеют следующие дополнительные ключи:

• preserve_keys - Если true, Контейнер попытается сохранить первичный ключ записи базы данных при установке.
• update_object - Если true, Контейнер ОБНОВИТ объект, если он уже был найден в базе данных во время установки. Если false, он будет пропущен.
• unique_key - имя столбца, по которому объект базы данных может быть однозначно идентифицирован - часто это не первичный ключ, поскольку автоматически увеличивающиеся поля часто не совпадают в разных базах данных.
• related_objects - сложный массив любых связанных объектов с основным объектом базы данных этого Контейнера. Иногда может потребоваться упаковать «связанные» объекты для достижения желаемого конечного результата. Отличный пример - если упаковщик хочет поместить все свои Сниппеты в Категорию. Он сделал бы объект Контейнера категорией, а затем добавил бы к нему связанные объекты - Сниппеты.
• related_object_attributes - атрибуты для вышеупомянутых связанных объектов.
• namespace - аналогично манифесту; значение группировки для объектов в ТП.

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

• validate - массив массивов, которые содержат "валидаторы", объяснение позже.
• resolve - массив массивов, которые содержат "преобразователи", объясненные позже.

В xPDOFileVehicles вы также увидите каталог с тем же именем, что и у Контейнера, за вычетом .vehicle. Если вы откроете его, там будут файлы для Контейнера.

Резольверы и валидаторы¶

Что такое "Резолверы" и "Валидаторы"? Думайте о них как скриптах, запускающихся до и после установки. По сути это PHP-скрипты. (На самом деле, если вы их откроете, они будут выглядеть точно так же, как PHP скрипты.) Их имена совпадают с именем файла ТС, но с добавлением постфикса .resolver или .validator.

Валидатор¶

Валидатор запускается перед установкой, обновлением или удалением Контейнера. Если он возвращают false, Контейнер не устанавливается и пропускается.

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

Резольвер¶

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

Резольверы полезны для "очистки" после установки Контейнера или для настройки параметров пользовательской конфигурации (например, параметров установки во время инсталляции).

Использование¶

Транспортными пакетами можно управлять в разделе Менеджер пакетов. Их можно добавить в MODX одним из следующих способов:

1. Загрузите файл вручную в каталог core/packages/, а затем нажмите кнопку "Загрузить пакеты" и выберите параметр "Искать пакеты локально".
2. Загрузка пакета из Транспортного провайдера. Это также позволяет удаленно загружать обновления для пакета.

После загрузки их можно установить, щелкнув правой кнопкой мыши пакет в списке и выбрав "Установить". Здест пользователю нужно будет принять лицензионное соглашение, если оно есть в пакете, и предложение ознакомиться с README файлом, если он есть в пакете. Затем он представит форму с параметрами предварительной установки, которые могут существовать или не существовать в зависимости от пакета. Затем пользователь может щелкнуть "Установить"»", чтобы установить пакет.

После установки пользователь может удалить пакет в любое время. Кроме того, если пакет был загружен из Транспортного провайдера, то пользователь может проверить наличие обновлений для пакета.

Смотрите еще¶

• Управление пакетами
• Провайдеры
• Руководство: Создание скрипта сборки