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

Использование package-info.xml в модах SMF

В этой статье мы разберем структуру файла package-info.xml и его роль в модификациях для SMF 2.1.

Прежде чем читать дальше, вы должны знать некоторые определения, используемые в этой документации:

  • Элемент (aka тег): инструкция, используемая для указания менеджеру пакетов, что делать, например <install></install>.
  • Атрибут (aka свойство): дополнительное значение, используемое для описания элемента.
  • Inline: код или текст, написанный непосредственно в этом файле, а не из внешнего источника.
  • File: имя или расположение файла, используемого вместо inline.
  • Location (aka path): расположение на компьютере директории и/или файла.

Также есть переменные, которые могут использоваться вместо пути:

  • $sourcedir: директория, где находятся исходные файлы (например, Post.php, Admin.php и т. д.).
  • $boarddir: директория, где находится файл SSI.php. Обычно на один уровень выше, чем директория с исходными файлами.
  • $avatardir: директория, где находятся аватары.
  • $themedir: директория, где расположены директории шаблонов.
  • $imagesdir: директория изображений для каждого шаблона.
  • $languagedir: расположение директорий языковых файлов.
  • $smileysdir: расположение директории смайликов.

Файл package-info.xml является одним из ключевых — это «метафайл», который определяет свойства мода, его совместимость с версиями SMF и действия по установке, обновлению или удалению. Без правильной структуры этого файла менеджер пакетов SMF не сможет корректно обработать мод.

Совет

Подробнее о создании модов, работающих на хуках, без правок файлов движка, читайте в статье Как подключать хуки.

Назначение файла package-info.xml⚓︎

Файл package-info.xml служит «инструкцией» для менеджера пакетов SMF. Он:

  • Определяет идентичность мода: Уникальный ID, название и версию.
  • Указывает тип пакета: Для модов это всегда “modification”.
  • Описывает совместимость: С какими версиями SMF мод работает (например, 2.1.0–2.1.99).
  • Список действий: Что делать при установке (<install>), обновлении (<upgrade>) или удалении (<uninstall>).
  • Управляет файлами и кодом: Копирование файлов, выполнение PHP-кода или SQL-запросов.

В SMF 2.1 этот файл особенно важен, так как система стала более строгой к совместимости, чтобы избежать конфликтов при обновлениях.

Основная структура файла⚓︎

Файл package-info.xml — это XML-документ с обязательным DOCTYPE и пространством имен SMF. Вот базовый шаблон:

<?xml version="1.0"?>
<!DOCTYPE package-info SYSTEM "http://www.simplemachines.org/xml/package-info">
<package-info xmlns="http://www.simplemachines.org/xml/package-info" xmlns:smf="http://www.simplemachines.org/">
    <!-- Основные свойства мода -->
    <id>unique:mod_name</id>  <!-- Уникальный ID, например, "developer:MyMod" -->
    <name>Название мода</name>
    <version>1.0</version>    <!-- Версия мода -->
    <type>modification</type> <!-- Тип: modification для модов -->

    <!-- Установка для SMF 2.1 -->
    <install for="2.1.0-2.1.99">
        <!-- Действия: копирование файлов, моды XML и т. д. -->
        <modification file="install.xml" />  <!-- Ссылка на файл с инструкциями по изменениям -->
        <code file="setup.php" />            <!-- Выполнение PHP-кода -->
        <database file="database.sql" />     <!-- SQL-запросы -->
        <hook hook="integrate_pre_load" function="some_function" file="$sourcedir/some_file.php"/> <!-- «Прописка» хуков (только в SMF 2.1) -->
        <require-dir name="some_dir" destination="$themes_dir" />  <!-- Копирование директорий -->
        <require-file name="some.php" destination="$sourcedir" />  <!-- Копирование файлов -->
        <readme file="readme.txt" parsebbc="true" />  <!-- Показ readme -->
    </install>

    <!-- Обновление -->
    <upgrade from="2.0.0-2.0.99" for="2.1.0-2.1.99">
        <!-- Действия по обновлению -->
    </upgrade>

    <!-- Удаление -->
    <uninstall for="2.1.0-2.1.99">
        <modification file="install.xml" reverse="true" />  <!-- Обратные изменения -->
        <hook hook="integrate_pre_load" function="some_function" file="$sourcedir/some_file.php" reverse="true" /> <!-- «Выписка» хуков (только в SMF 2.1) -->
        <remove-dir name="$sourcedir/MyMod" />        <!-- Удаление директорий -->
        <remove-file name="$sourcedir/source.php" />        <!-- Удаление файлов -->
    </uninstall>
</package-info>

Основные элементы⚓︎

  • <id>: Уникальный идентификатор мода в формате «разработчик:имя_мода» (например, john_doe:MyCoolMod). Обязателен для избежания конфликтов.
  • <name>: Название мода, отображаемое в менеджере пакетов.
  • <version>: Версия мода (например, 1.0).
  • <type>: Для модификаций — modification. Другие типы: theme, language, avatar.
  • <install for="...">: Блок для установки мода. Атрибут for задает диапазон совместимых версий SMF (например, 2.1.0-2.1.99).
  • <modification>: Ссылка на XML-файл с инструкциями по редактированию кода (например, install.xml).
  • <code>: Выполняет PHP-код (атрибут file для файла или type="inline" для встроенного кода).
  • <database>: Выполняет SQL-запросы из указанного файла. Атрибуты: type (inline или file, по умолчанию file).
  • <hook>: Регистрирует хуки в базе данных. Поддерживается только в SMF 2.1 и выше.
  • <require-file>: Указывает файлы для установки. Атрибуты: from (путь к файлу внутри пакета), name (имя файла), destination (куда установить).
  • <require-dir>: Указывает директории для установки. Атрибуты: from (путь к директории внутри пакета), name (имя директории), destination (куда установить).
  • <remove-file>: Указывает файлы для удаления.
  • <remove-dir>: Указывает директории для удаления.
  • <create-dir>: Создает новую директорию. Атрибуты: name (имя директории), destination (где создать).
  • <create-file>: Создает пустой файл. Атрибуты: name (имя файла), destination (где создать).
  • <move-dir>: Перемещает директорию. Может использоваться для переименования. Атрибуты: from (путь исходной директории), name (имя директории), destination (куда переместить).
  • <move-file>: Перемещает файл. Может использоваться для переименования. Атрибуты: from (путь исходного файла), name (имя файла), destination (куда переместить).
  • <readme>: Отображает инструкции для пользователя. Атрибуты: lang (язык readme), parsebbc (парсить BBCode, по умолчанию false), type (inline или file, по умолчанию file).
  • <redirect>: Перенаправляет пользователя после установки. Атрибуты: url (обязательный, принимает “$boardurl”, “$scripturl”, “$session_id”), timeout (время до перенаправления, по умолчанию 5 секунд).
  • <uninstall>: Блок для удаления мода. Использует reverse="true" для отмены изменений в файлах.
  • <upgrade>: Блок для обновления мода (например, миграция данных при переходе с версии 1.0 на 1.1). Атрибуты: for (диапазон версий), from (версии, с которых обновляется).
  • <operation>, <search>, <add>: Используются для inline-изменений кода (редактирование файлов без отдельного XML).

Использование в модификациях SMF 2.1⚓︎

Создание мода⚓︎

1) Создайте файлы мода:

  • package-info.xml: Основной файл с метаинформацией.
  • install.xml: Инструкции по изменению исходного кода SMF (необязательно, если у вас мод на хуках).

2) Дополнительные файлы: PHP-скрипты, SQL-запросы, языковые файлы, изображения.

3) Задайте совместимость: В <install for="2.1.0-2.1.99"> укажите действия, специфичные для SMF 2.1 (например, использование хуков).

4) Тестирование: Загрузите мод через менеджер пакетов в админ-панели SMF. Если возникают ошибки, проверьте пути к файлам и версии.

5) Обновление: Для поддержки обновлений добавьте блок <upgrade> с инструкциями по миграции.

Пример⚓︎

Предположим, вы создаете мод, добавляющий поддержку внешнего поиска (например, Sphinx). Блоки install и uninstall в package-info.xml могут выглядеть так:

<install for="2.1.0-2.1.99">
    <require-file name="SearchAPI-Sphinxql.php" destination="$sourcedir/" />
    <require-file name="Admin-Sphinx.english.php" destination="$themes_dir/default/languages/" />
    <database file="install_sphinx.sql" />
    <redirect url="?action=admin;area=managesearch;sa=method" timeout="3" />
</install>

<uninstall for="2.1.0-2.1.99">
    <remove-file name="$sourcedir/SearchAPI-Sphinxql.php" />
    <remove-file name="$themes_dir/default/languages/Admin-Sphinx.english.php" />
    <database file="uninstall_sphinx.sql" />
</uninstall>

Этот код копирует PHP-файлы, добавляет языковые файлы и выполняет SQL-запросы для настройки поиска, а после установки перенаправляет администратора в настройки поиска.

Как выполнить код при установке мода⚓︎

Добавьте в package-info.xml в секцию install строку <code type="inline"><!-- ваш php-код в виде одной строки --></code>:

<install>
    <code type="inline">phpinfo();</code>
</install>

Например, вот так можно проверить используемую версию PHP и прекратить дальнейшую установку:

<install>
    <code type="inline"><![CDATA[<?php
            define('REQUIRED_PHP_VERSION', '7.4.0');
            if (version_compare(PHP_VERSION, REQUIRED_PHP_VERSION, '<'))
                fatal_error(
                    sprintf(
                        'This mod requires a minimum of PHP %s in order to function. (You are currently running PHP %s)',
                        REQUIRED_PHP_VERSION,
                        PHP_VERSION
                    ),
                    false
                );
        ?>]]></code>
</install>

Кроме того, можно запустить на выполнение целый файл:

<install>
    <code>file.php</code>
</install>

Лучшие практики⚓︎

  • Совместимость: Используйте диапазоны версий (2.1.0-2.1.99) для покрытия всех минорных обновлений SMF 2.1.
  • Безопасное удаление: В <uninstall> всегда добавляйте reverse="true" для модификаций и аккуратно удаляйте файлы, чтобы не повредить систему.
  • Документация: Включите <readme> с понятными инструкциями для пользователей.
  • Ошибки установки: Если мод не устанавливается, используйте функцию «Эмуляция версии» в менеджере пакетов для проверки совместимости.
  • Сохранение данных: Избегайте удаления таблиц базы данных в <uninstall>, чтобы пользователи не потеряли данные.
  • Тестирование: Проверяйте мод на чистой установке SMF 2.1, чтобы избежать конфликтов с другими модами.

Частые ошибки и их решения⚓︎

  • Ошибка «Invalid package»: Проверьте синтаксис XML и наличие DOCTYPE.
  • Несовместимость версий: Убедитесь, что атрибут for включает нужные версии SMF.
  • Файлы не копируются: Проверьте правильность путей и плейсхолдеров ($sourcedir/, $themedir/).
  • Конфликты модов: Уникальный <id> предотвращает пересечения. Используйте формат ваш_ник:имя_мода.

Памятка о подстановках, используемых в package-info.xml⚓︎

<?php

'\\'             => '/',
'$boarddir'      => $boarddir,
'$sourcedir'     => $sourcedir,
'$avatardir'     => $modSettings['avatar_directory'],
'$avatars_dir'   => $modSettings['avatar_directory'],
'$themedir'      => $settings['default_theme_dir'],
'$imagesdir'     => $settings['default_theme_dir'] . '/' . basename($settings['default_images_url']),
'$themes_dir'    => $boarddir . '/Themes',
'$languagedir'   => $settings['default_theme_dir'] . '/languages',
'$languages_dir' => $settings['default_theme_dir'] . '/languages',
'$smileysdir'    => $modSettings['smileys_dir'],
'$smileys_dir'   => $modSettings['smileys_dir']

Заключение⚓︎

Файл package-info.xml — это основа любой модификации для SMF 2.1, обеспечивающая автоматизацию установки, обновления и удаления. Правильная структура файла делает моды надёжными и удобными для пользователей. Для углубленного изучения обратитесь к официальной документации SMF или изучите примеры популярных модификаций. Начните с шаблона, следуйте лучшим практикам — и ваш мод станет полезным дополнением к любому форуму на SMF 2.1!

Полезняшки⚓︎

Package SDK Simple Mod Maker

Комментарии