Перейти к содержанию

Быстрый старт

Пошаговое руководство: от установки до готового transport.zip за 5 минут. Используем headless-режим — без MODX, без MySQL, без сервера.

1. Установка

composer global require shevartv/modx-builder

Подробнее о вариантах установки и настройке PATH: Установка

2. Настройка окружения

mkdir my-package && cd my-package
modxapp setup

Создайте папку проекта и перейдите в неё. Затем modxapp setup скачает ядро MODX 3, установит зависимости и настроит окружение для headless-сборки. Все последующие команды выполняются из этой папки. Настройка делается один раз для проекта.

Если у вас уже установлен MODX — этот шаг не нужен, Package Builder найдёт core/config/config.inc.php автоматически.

3. Глобальные настройки

modxapp config

Введите данные автора (имя, email, git-логин). Они сохранятся и будут использоваться при создании всех пакетов.

4. Создание пакета

modxapp create my-package --elements

Будет создана стандартная структура компонента MODX 3:

core/components/my-package/
├── bootstrap.php              — точка входа
├── composer.json              — зависимости и скрипты
├── phpstan.neon               — конфигурация PHPStan
├── docs/                      — readme, license, changelog
├── lexicon/                   — файлы переводов
├── schema/                    — XML-схема БД
├── src/                       — PHP-классы
│   ├── MyPackage.php          — главный класс
│   └── Plugins/IPlugin.php    — интерфейс плагинов
└── elements/                  — файлы элементов
    ├── plugins/switch.php     — единая точка входа плагинов
    └── snippets/connector.php

package_builder/packages/my-package/
├── config.php                 — конфигурация сборки
└── elements/                  — описание элементов для сборки
    ├── snippets.php
    └── plugins.php

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

modxapp templates copy ecommerce       # скопировать default в package_builder/templates/ecommerce/
# Отредактировать шаблон под свои нужды
modxapp create my-shop --template=ecommerce

Подробнее: Управление шаблонами

5. Описание элементов

Элементы описываются в двух местах:

  • Описание (что собирать) — PHP-файлы в package_builder/packages/<name>/elements/
  • Контент (код, HTML) — файлы в core/components/<name>/elements/
package_builder/packages/my-package/
└── elements/
    ├── chunks.php          — описание чанков
    ├── snippets.php        — описание сниппетов
    ├── plugins.php         — описание плагинов
    └── ...

core/components/my-package/
└── elements/
    ├── chunks/
    │   └── hello.tpl       — HTML-код чанка
    ├── snippets/
    │   └── mysnippet.php   — PHP-код сниппета
    └── plugins/
        └── myplugin.php    — PHP-код плагина

Чанки

Чанки удобнее хранить как статичные — контент в файле, MODX читает его напрямую:

// package_builder/packages/my-package/elements/chunks.php
<?php
return [
    'tpl.my-package.hello' => [
        'description' => 'Приветственный чанк',
        'content' => 'file:elements/chunks/hello.tpl',
    ],
];

Контент чанка в core/components/my-package/elements/chunks/hello.tpl:

<p>Привет, [[+name]]!</p>

Чтобы чанк был статичным (MODX читает из файла, а не из БД), в config.php пакета должно быть:

'static' => [
    'chunks' => true,
],

Сниппеты

Аналогично — код в отдельном файле:

// package_builder/packages/my-package/elements/snippets.php
<?php
return [
    'mySnippet' => [
        'file' => 'mysnippet.php',
        'description' => 'Мой сниппет',
    ],
];

Код сниппета в core/components/my-package/elements/snippets/mysnippet.php:

<?php
return 'Hello from my snippet!';

Статичные сниппеты (код читается из файла):

'static' => [
    'snippets' => true,
],

Статичные элементы

Статичные элементы удобны при разработке — вы редактируете файл в IDE, и изменения сразу видны на сайте без пересборки пакета. Настройка static в config.php определяет какие типы элементов будут статичными.

Плагины

// package_builder/packages/my-package/elements/plugins.php
<?php
return [
    'myPlugin' => [
        'file' => 'myplugin.php',
        'description' => 'Мой плагин',
        'events' => [
            'OnPageNotFound' => [],
            'OnLoadWebDocument' => ['priority' => 0],
        ],
    ],
];

Код плагина в core/components/my-package/elements/plugins/myplugin.php.

Системные настройки

// package_builder/packages/my-package/elements/settings.php
<?php
return [
    'my_api_key' => [
        'value' => '',
        'xtype' => 'textfield',
        'area' => 'general',
    ],
    'my_debug' => [
        'value' => '0',
        'xtype' => 'combo-boolean',
        'area' => 'system',
    ],
];

Меню

// package_builder/packages/my-package/elements/menus.php
<?php
return [
    'my-package' => [
        'description' => 'my_menu_desc',
        'action' => 'home',
        'parent' => 'components',
    ],
];

Все поддерживаемые типы элементов: Команда elements

6. Извлечение данных из кода

Если в PHP-коде вашего компонента есть вызовы лексиконов и настроек — Package Builder найдёт их автоматически:

# Найти все $modx->lexicon('key') и собрать ключи
modxapp extract-lexicons my-package

# Найти все $modx->getOption('key') и создать файл настроек
modxapp extract-settings my-package

7. Сборка

modxapp build my-package

Результат — файл core/packages/my-package-1.0.0-alpha.transport.zip, готовый для установки на любой MODX 3.

Проверки перед сборкой

Перед сборкой автоматически запускаются PHPStan, PHP CS Fixer и ESLint (если установлены). Чтобы пропустить:

modxapp build my-package --no-check

8. Установка на MODX

Скопируйте transport.zip в core/packages/ на сайте MODX и установите через менеджер пакетов в админке.

Или если Package Builder установлен на сервере с MODX:

modxapp build my-package --install

Что дальше