Helgring XF Release Builder 1.1.0

[Shum1kh1n]

Shum1kh1n опубликовал новый ресурс:

Helgring XF Release Builder - Инструмент для удобной подготовки и сборки релизов аддонов

Helgring XF Release Builder​

---

Посмотреть вложение 436​

---

✦ Утилита для пересборки hashes.json и правильной упаковки релизов XenForo ✦​

---

Утилита создана для удобной работы с релизами аддонов XenForo. Она...

Подробнее об этом ресурсе...

 

[Shum1kh1n]

Shum1kh1n обновил(а) ресурс Helgring XF Release Builder новым обновлением:

Обновление до версии 1.1.0

Обновление до версии 1.1.0​

---

✦ Полная переработка утилиты: переход на официальный механизм XenForo, удалённая SSH-сборка релизов и выпуск публичной EXE-версии ✦​

---

Что было обновлено:...

Читать остальную часть этого обновления...

 

[Shum1kh1n]

Как правильно настроить config.json для Helgring XF Release Builder​

---

✦ Подробная инструкция по заполнению config.json, поиску правильного пути форума, настройке SSH-параметров и подготовке утилиты к работе ✦​

---

Что такое config.json и зачем он нужен:
Файл config.json — это основной конфигурационный файл утилиты Helgring XF Release Builder. Именно в нём указываются все параметры, которые нужны программе для подключения к серверу и сборки релиза XenForo.

Проще говоря, config.json сообщает утилите:

• куда подключаться — SSH-хост, порт и логин;
• где находится форум — рабочий путь до XenForo;
• какой PHP CLI использовать — чтобы команды XenForo запускались корректно;
• какой add-on собирать — идентификатор дополнения;
• где искать готовый ZIP — путь до папки _releases.

Без правильно заполненного config.json утилита не сможет запустить сборку.

---

Где должен лежать config.json:
Файл config.json должен лежать в одной папке с EXE-файлом утилиты.

Helgring XF Release Builder.exe
config.json

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

---

Где вводить команды для проверки пути и окружения:
Все команды, которые приведены ниже, нужно вводить не в самой утилите, а в SSH-терминале. Это может быть:

• Termius
• встроенный SSH-терминал хостинга
• PuTTY
• любой другой SSH-клиент

Сначала пользователь подключается по SSH к своему серверу, а уже после входа в SSH-сессию вводит команды проверки пути, PHP и структуры форума.

---

Базовая структура config.json:
Внутри файла обязательно должен быть объект profiles. В нём хранится один или несколько профилей. Каждый профиль — это отдельный набор параметров для конкретного сервера, dev-форума или add-on-проекта.

{
  "profiles": {
    "мой_профиль": {
      "host": "ваш_IP_или_домен_сервера",
      "port": 22,
      "username": "ваш_ssh_логин",
      "forum_root": ".",
      "php_bin": "/путь/до/php",
      "addon_id": "Vendor/AddOn",
      "release_dir": "src/addons/Vendor/AddOn/_releases",
      "download_dir": "./downloads",
      "timeout": 60,
      "run_sync_json": false,
      "auth": {
        "method": "password"
      }
    }
  }
}

---

Расшифровка каждого параметра:

• host — адрес сервера для SSH-подключения. Это может быть IP-адрес или доменное имя SSH-сервера.
• port — SSH-порт. Обычно это 22, если хостинг не использует другой порт.
• username — SSH-логин пользователя, под которым выполняется вход на сервер.
• forum_root — рабочий путь до корня форума XenForo с точки зрения SSH-сессии.
• php_bin — полный путь до PHP CLI, через который будут запускаться команды XenForo.
• addon_id — идентификатор дополнения в формате Vendor/AddOn.
• release_dir — путь до папки _releases, где XenForo создаёт готовый ZIP-архив.
• download_dir — папка на компьютере пользователя, куда утилита скачает собранный архив.
• timeout — таймаут SSH-операций в секундах.
• run_sync_json — запускать ли xf-addon:sync-json перед сборкой. Если не требуется — можно оставить false.
• auth.method — способ авторизации: password для пароля или key для SSH-ключа.

---

Как узнать правильный forum_root:
Это один из самых важных параметров. Именно здесь пользователи чаще всего ошибаются.
После подключения по SSH нужно понять, в какой папке реально находится форум XenForo, а не какой путь показывает FTP-клиент или панель хостинга.
Шаг 1. После входа по SSH выполните команду:

pwd

Эта команда покажет текущую рабочую папку, в которой вы находитесь после входа по SSH.
Шаг 2. Посмотрите содержимое текущей папки:

ls -la

Если в этой папке вы уже видите файлы и каталоги XenForo, например:

• cmd.php
• src
• js
• styles
• src/config.php

значит вы уже находитесь в корне форума. В таком случае можно указать:

"forum_root": "."

Точка . означает: использовать текущую папку как рабочую.
Шаг 3. Проверьте, действительно ли в текущей папке лежит XenForo:

ls -la cmd.php
ls -la src/config.php

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

find . -maxdepth 3 -name cmd.php 2>/dev/null

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

./cmd.php

это означает, что cmd.php лежит прямо в текущей папке, а значит forum_root = "." подходит правильно.
Если же команда возвращает, например:

./public_html/cmd.php

то в таком случае нужно использовать уже другой путь, например:

"forum_root": "./public_html"

---

Почему у одного пользователя forum_root = ".", а у другого нет:
Потому что разные хостинги и разные SSH-аккаунты ведут себя по-разному.

• У одного пользователя SSH сразу открывается в корне форума — тогда подходит .
• У другого пользователя SSH открывается в домашней папке, а форум лежит глубже — тогда нужно указывать путь вроде ./public_html или другой реальный рабочий каталог.
• FTP-путь и SSH-путь не всегда совпадают. Именно поэтому путь нужно проверять через SSH-команды, а не угадывать.

---

Как узнать правильный php_bin:
После входа по SSH можно проверить, какой PHP вообще доступен, с помощью команд:

which php
php -v
php --ini

Но важно понимать, что обычный php из PATH не всегда подходит. На некоторых хостингах рабочий CLI-бинарник может быть, например:

/usr/local/bin/php8.3

Проверить это можно так:

/usr/local/bin/php8.3 -v
/usr/local/bin/php8.3 -m | grep -i '^mbstring$'

Если версия PHP выводится, а mbstring найден, значит этот путь подходит для php_bin.

---

Как определить правильный addon_id:
Поле addon_id должно совпадать с реальным путём в src/addons.
Например, если ваш add-on лежит здесь:

src/addons/Spolzer/StickyPost

тогда addon_id должен быть таким:

"addon_id": "Spolzer/StickyPost"

Если путь выглядит так:

src/addons/Helgring/MessageNoticePro

тогда правильно будет:

"addon_id": "Helgring/MessageNoticePro"

---

Как определить правильный release_dir:
Поле release_dir должно указывать на папку _releases именно того add-on, который вы собираете.
Примеры:

"release_dir": "src/addons/Spolzer/StickyPost/_releases"

"release_dir": "src/addons/Helgring/MessageNoticePro/_releases"

Если путь указан неверно, утилита может успешно собрать релиз на сервере, но потом не сможет найти ZIP для скачивания.

---

Пример готового config.json для обычного пользователя:

{
  "profiles": {
    "мой_профиль": {
      "host": "123.123.123.123",
      "port": 22,
      "username": "мой_ssh_логин",
      "forum_root": ".",
      "php_bin": "/usr/local/bin/php8.3",
      "addon_id": "Spolzer/StickyPost",
      "release_dir": "src/addons/Spolzer/StickyPost/_releases",
      "download_dir": "./downloads",
      "timeout": 60,
      "run_sync_json": false,
      "auth": {
        "method": "password"
      }
    }
  }
}

В этом примере пользователю нужно заменить только свои реальные данные:

• IP сервера или хост
• SSH-логин
• правильный путь до PHP CLI
• идентификатор своего add-on
• путь до папки _releases

---

Частые ошибки пользователей:

• Неверный forum_root — пользователь указывает красивый FTP-путь из панели хостинга, но в SSH этот путь не работает.
• Неверный php_bin — пользователь пишет просто php, хотя рабочий CLI-путь на сервере другой.
• Неверный addon_id — из-за этого утилита не находит каталог дополнения.
• Неверный release_dir — утилита не может найти готовый ZIP после сборки.
• Ошибки синтаксиса в JSON — лишние запятые, неправильные кавычки или поломанная структура файла.

---

FAQ:

• Можно ли использовать один профиль? Да. Это самый простой вариант. Если профиль в config.json только один, утилита может использовать его автоматически.
• Можно ли хранить несколько профилей? Да. Это удобно, если вы собираете несколько разных add-on-проектов.
• Нужно ли редактировать EXE-файл? Нет. Пользователь меняет только config.json.
• Что делать, если не получается определить forum_root? Подключиться по SSH и проверить команды pwd, ls -la, ls -la cmd.php, ls -la src/config.php, find . -maxdepth 3 -name cmd.php 2>/dev/null.
• Что делать, если программа не подключается по SSH? Проверить host, port, username, правильность пароля или SSH-ключа, а также доступность SSH на сервере.
• Что делать, если программа не находит add-on? Проверить поля addon_id и forum_root.
• Что делать, если готовый ZIP не скачивается? Проверить release_dir и убедиться, что релиз действительно был создан в папке _releases.

---

Итог:
Файл config.json — это центральная часть настройки Helgring XF Release Builder. Если он заполнен правильно, утилита сможет подключиться к серверу, проверить окружение, официально собрать релиз XenForo и скачать готовый архив на компьютер пользователя.

Главное правило простое: не угадывать пути, а проверять их через SSH. Именно это помогает правильно определить forum_root, php_bin и другие ключевые параметры без лишних ошибок.

 

[Shum1kh1n]

---

Как правильно включать JS, Styles и внешние файлы в релиз:
Если add-on использует не только файлы внутри src/addons/Vendor/AddOn, но и внешние ресурсы вроде js, styles или отдельных файлов в корне upload, то для их корректной сборки через xf-addon:build-release необходимо явно указать их в специальном файле build.json.

По умолчанию XenForo не будет автоматически угадывать и добавлять такие внешние файлы в релиз. Если их не описать отдельно, они не попадут ни в ZIP-архив, ни в hashes.json. Поэтому для правильной сборки релиза нужно заранее подготовить add-on к работе с дополнительными файлами.

---

Где нужно создать build.json:
Файл build.json создаётся внутри папки самого add-on, рядом с addon.json. То есть путь должен быть таким:

src/addons/Vendor/AddOn/build.json

Для примера с KL EditorManager это будет:

src/addons/KL/EditorManager/build.json

---

Что нужно записать в build.json:
Если плагин использует внешние JavaScript-файлы, style-ресурсы и отдельный публичный файл klEMProxy.php, то содержимое build.json должно быть примерно таким:

{
  "additional_files": [
    "js/editor-manager",
    "styles/editor-manager",
    "klEMProxy.php"
  ]
}

Именно этот блок сообщает XenForo, что при сборке релиза нужно дополнительно включить в архив:

• папку upload/js/editor-manager
• папку upload/styles/editor-manager
• файл upload/klEMProxy.php

---

Важно: одних записей в build.json недостаточно
Файл build.json сам по себе не создаёт ресурсы автоматически. Он только указывает XenForo, какие внешние файлы нужно забрать в релиз. Поэтому эти файлы должны реально существовать в исходной структуре add-on.

Иными словами, если в плагине используются js, styles и отдельные внешние PHP-файлы, они должны быть правильно подготовлены в исходниках до запуска xf-addon:build-release.

---

Как понять, какие внешние файлы вообще использует плагин:
Это очень важный момент. Перед созданием build.json нужно сначала определить, какие именно внешние пути реально относятся к конкретному add-on. Для этого можно использовать несколько простых способов:

• Проверить оригинальный архив плагина — если в исходном релизе уже есть папки upload/js/..., upload/styles/... или отдельные файлы вроде upload/klEMProxy.php, значит они относятся к add-on и должны быть учтены в новой сборке.
• Посмотреть hashes.json оригинального архива — если в hashes.json есть записи на js/..., styles/... или отдельные файлы в корне upload, значит они тоже входят в релизный состав плагина.
• Проверить код add-on — иногда внешний файл прямо упоминается в PHP-классе, шаблоне или proxy-логике. Например, в KL EditorManager использовались klEMProxy.php, missing-audio.mp3 и missing-video.mp4, поэтому их отсутствие ломало или урезало часть функционала.
• Проверить структуру работы плагина — если дополнение подключает собственный JavaScript, SVG-иконки, proxy-файлы, аудио/видео-заглушки или style-ресурсы, значит эти внешние элементы нужно явно учитывать при сборке.

---

Пример на практике для KL EditorManager:
В случае KL EditorManager в релизе использовались следующие внешние файлы:

• js/editor-manager — JavaScript-файлы плагина
• styles/editor-manager — SVG и мультимедийные заглушки
• klEMProxy.php — публичный proxy-файл

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

---

Итог:
Если add-on использует внешние ресурсы вне стандартной папки src/addons, то их необходимо явно описывать через build.json. Без этого XenForo не включит их в официальный релизный архив.

Главное правило простое: сначала определить, какие внешние файлы реально использует плагин, а уже потом добавить их в additional_files. Именно это позволяет получить полный ZIP-архив и корректный hashes.json без пропусков по js, styles и другим внешним ресурсам.

 

[Shum1kh1n]

Если у Вас остались вопросы, задавайте их непосредственно в данной теме.