Як встановити власне доповнення: модуль, тему чи мову архівом
Два вимикачі, огляд і встановлення, що перевіряється в архіві, часті причини відмови та чим відрізняється архів з підписом 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; відкотитися можна завантаженням попереднього архіву з позначкою «підтверджую заміну». - Встановлення записується в журнал, а власникам сайту йде лист із назвою, версією та підписом.
Як написати те, що ви встановлюєте: Власний модуль, Власна тема, Власна мова й мовний пакет. Загальна довідка щодо можливості — у статті Встановлення модуля чи теми з архіву.