Как поставить своё дополнение: модуль, тему или язык архивом
Два выключателя, осмотр и установка, что проверяется в архиве, частые причины отказа и чем отличается архив с подписью Nex1on.
Свой модуль, свою тему или свой язык (файл .zip, собранный командами module:pack, theme:pack, language:pack или вручную) ставят на сайт одной страницей: Дополнения → Модули → Установить из архива. Архив — это чужой код, который потом работает на вашем сервере, поэтому всё сделано осторожно: ставит только владелец, каждый шаг под паролем, а сначала архив только осматривается.
Два выключателя
На странице установки два выключателя. Они одни на модули, темы и языковые пакеты.
| Выключатель | Что делает |
|---|---|
| Установка из архива | по умолчанию выключена. Пока она выключена, загрузка и установка отвечают «не найдено», а страница показывает только сам выключатель. Включает владелец кнопкой «Включить» с паролем. Включайте, только если знаете, откуда будут архивы |
| Разрешить архивы без подписи | по умолчанию выключен. Без него ставятся только архивы с подписью Nex1on. Свои архивы подписи не имеют, поэтому для них выключатель нужно включить; для чужих — не включайте |
Два шага
- Осмотр. Выберите, что ставите: «Модуль», «Тема» или «Языковой пакет», загрузите файл .zip (до 20 МБ), введите пароль и нажмите «Осмотреть». Архив распаковывается во временную закрытую папку, читается описание и проверяется подпись. Ничего не устанавливается и не запускается. В ответ — отчёт «Что в архиве»: название и версия, число файлов и размер, подпись («Подписан Nex1on» или «Без подписи») и, если такое уже стоит, что будет заменено.
- Установка. Отметьте «Я понимаю, что код этого архива будет выполняться на моём сервере» (для языкового пакета — что тексты увидят посетители), введите пароль и нажмите «Установить». Осмотр действует 15 минут и только для вас; перед установкой файлы проверяются ещё раз, и если они успели измениться, установка откажет.
Установка ставит только файлы. Модуль остаётся выключенным и его миграции не выполняются; тема не включается; язык остаётся выключенным. Дальше:
| Что поставили | Что сделать |
|---|---|
| модуль | «Дополнения → Модули», у карточки «Установить и включить». Перед включением сделайте копию базы: включение запускает код модуля с теми же правами, что и сайт |
| тема | «Оформление → Темы», «Сделать активной» |
| языковой пакет | «Языки и тексты → Языки», у языка «Включить» |
Что проверяется в архиве
| Проверка | Предел или правило |
|---|---|
| размер | архив до 20 МБ, не больше 2000 файлов, распакованный не больше 100 МБ, файл не больше 20 МБ; «раздувающийся» архив (сжатие больше чем в сто раз) отвергается |
| имена файлов | только латинские буквы, цифры, точка, подчёркивание и дефис; без пробелов и кириллицы, не длиннее 200 знаков; имя не начинается с точки (.gitignore, .DS_Store не годятся) и не совпадает с зарезервированным в Windows (con, nul, aux…); без повторов |
| ссылки и спецфайлы | символических ссылок и спецфайлов в архиве быть не должно |
| типы файлов | php, json, md, txt, html, xml, csv, css, js, png, jpg, jpeg, gif, webp, ico, woff, woff2, а также license, readme, notice, changelog без расширения. Картинки svg — только в архиве с подписью Nex1on |
| PHP | только в папках src, views, database, demo и файлом routes.php в корне; в теме без подписи Nex1on PHP нет вообще |
| описание | есть module.json или theme.json (для языка — language.json); имя в нём совпадает с именем папки; имя не занято встроенным модулем и не служебное слово |
| языковой пакет | в архиве только описание языка и файлы переводов в JSON; строки без разметки и опасных ссылок |
| подпись | подпись сходится с содержимым архива, ключ не отозван |
| замена | включённую версию заменить нельзя (сначала выключите); более старую версию или архив с другой подписью — только с отдельной отметкой; встроенный модуль заменяет только более новый архив с подписью Nex1on |
Код при осмотре и установке не запускается: файлы только лежат на диске. Команды module:pack и theme:pack делают ту же проверку состава заранее, поэтому архив, который они собрали, до этого пункта обычно доходит целым.
Частые причины отказа
| Что написано | Что делать |
|---|---|
| «Сначала включите установку из архива» | включите первый выключатель (владелец, пароль) |
| «Архив не подписан Nex1on: нужно разрешение «без подписи» и отметка «я понимаю»» | для своего архива включите второй выключатель и отметьте «Я понимаю…»; чужой архив без подписи лучше не ставить |
| «В архиве недопустимое имя файла» | переименуйте файл латиницей без пробелов, уберите файлы с точки в начале (.gitignore, .DS_Store) |
| «В архиве файл недопустимого типа» | уберите файл (svg, ttf, exe, zip внутри архива, файл без расширения) или замените png, webp, woff2 |
| «PHP-файл в недопустимом месте» | перенесите PHP в src, views, database или demo; в корне допустим только routes.php |
| «В теме без подписи нельзя PHP-файлы» | перепишите шаблоны на тегах, PHP в теме не нужен |
| «Не найден или неверен module.json / theme.json» | файл должен лежать в корне папки модуля внутри архива; проверьте JSON |
| «Папка в архиве называется не так, как модуль» | название папки внутри архива и name в описании должны быть одинаковыми |
| «Это имя занято» | выберите другое имя: встроенные модули и служебные слова (admin, api, core…) заняты |
| «Встроенный модуль можно заменить только более новым архивом с подписью Nex1on» | свой модуль не должен называться, как встроенный |
| «Эта версия включена: сначала выключите её» | выключите модуль или переключитесь на другую тему и ставьте снова |
| «Версия старее установленной» или «Подпись отличается от прежней» | если это сделано намеренно, отметьте подтверждение и загрузите архив заново |
| «Архив слишком большой», «слишком много файлов», «слишком раздувается» | уберите лишнее из архива: образцы, исходники картинок, копии |
| «Файл не открывается как zip» | пересоберите архив обычным zip (не rar, не 7z) |
| «Осмотр устарел или не ваш» | осмотр живёт 15 минут: загрузите архив заново |
| «Слишком часто: не больше пяти раз в час» | подождите; такой предел стоит нарочно |
| «Подпись не сходится с содержимым» | архив изменили после подписи или подпись чужая: возьмите оригинал |
Чем отличается архив с подписью Nex1on
Архив, собранный и подписанный нами (из каталога дополнений или присланный нами), ставится сразу: подпись проверяется, и мы знаем, что в нём лежит. Только в нём допустимы svg и PHP в теме. Свой архив подписи не имеет: мы не знаем, кто его собрал и что внутри, а его код получит полный доступ к сайту и базе. Поэтому такой архив ставится, только если владелец отдельно разрешил «без подписи» и в отчёте отметил, что понимает риск. Если на сервере нечем проверить подпись, подписанные архивы не принимаются.
Что остаётся после установки
- Старая версия, если она была, сохраняется в
storage/backups; откатиться можно загрузкой прежнего архива с отметкой «подтверждаю замену». - Установка записывается в журнал, а владельцам сайта уходит письмо с названием, версией и подписью.
Как написать то, что вы ставите: Свой модуль, Своя тема, Свой язык и языковой пакет. Общая справка по возможности — в статье Установка модуля или темы из архива.