Пакування та публікація теми

Тема для одного магазину живе папкою на диску. Щоб її можна було поставити в чужий магазин — з файлу або з маркетплейсу, — її збирають у пакет.

Збірка#

php artisan cartix:theme-build my-theme
php artisan cartix:theme-build my-theme --output=/шлях/my-theme.zip

За замовчуванням архів лягає в storage/app/dist/themes/<id>-<версія>.zip. Команда друкує розмір, число файлів, відбиток пакета і готовий рядок для реєстрації випуску.

Збірка відмовиться, якщо:

• у папці немає theme.json;
• theme.json не читається як JSON;
• не заповнено id, name або version;
• id усередині файлу не збігається з іменем папки.

Останнє важливо: адреса теми в маркетплейсі — це і є її ідентифікатор, і установник у клієнта їх звіряє. Пакет, підписаний під іншу тему, він ставити відмовиться.

Що потрапляє в пакет#

Усі файли теми, крім:

• службових папок: .git, node_modules, .github, .idea, .vscode;
• службових файлів: .env, .DS_Store, Thumbs.db, .gitignore;
• assets/plugins/ і templates/plugins/.

Останнє — не дрібниця. Ці папки наповнюють встановлені в клієнта доповнення: там лежать їхні шаблони і стилі. Вони належать його магазину, а не вам. Потрап вони в пакет — установлення вашої теми затерло б його блоки.

Про ці папки хвилюватися не потрібно: коли клієнт поставить доповнення, воно саме покладе туди свої файли. Ваше завдання — залишити в розмітці точки вбудовування там, де їм місце.

⚠️ Порожня папка в архів не потрапляє — складається перелік файлів. Завели assets/css/ без жодного файлу — у клієнта цієї папки не буде.

Версія магазину, на яку розрахована тема#

"requires": { "core": "2.0.0" }                            ця версія і новіші
"requires": { "core": ">=2.0.0" }                          те саме, зі знаком
"requires": { "core": { "min": "2.0.0", "max": "3.0" } }   з верхньою межею

Звичайний випадок — тільки нижня межа.

Ставте ту версію, можливостями якої тема справді користується, і переконайтеся, що ця версія магазину вже вийшла. Інакше клієнт купить тему, яка не встановиться.

Перевірка йде до підміни папки, тому відмова безпечна: попередня тема залишається на місці, магазин працює, а власник бачить зрозуміле повідомлення про те, що спочатку потрібно оновити магазин.

Викладення в маркетплейс#

cartix:theme-build my-theme
# → завантажити архів на Store, завести картку теми в каталозі
cartix:release-register my-theme 1.2.0 шлях/до/my-theme-1.2.0.zip --publish

Пакет підписується під час реєстрації, і установник у клієнта перевіряє підпис. Без реєстрації випуску клієнт тему не отримає — файли тем у магазин не входять.

У кожного випуску має бути «що нового» всіма мовами картки. Власник бачить ці рядки під час оновлення, і випуск без пояснення виглядає як «щось змінили, а що — невідомо». Пишіть про те, що власник отримує, а не про те, який файл поправили.

Як проходить оновлення в клієнта#

Нова версія спочатку повністю розкладається поруч — покупці в цей час бачать стару тему, — і тільки потім папки міняються місцями. Збій на будь-якому кроці повертає попередню тему, і магазин продовжує працювати.

Після заміни скомпільовані шаблони скидаються самі. Папки assets/plugins/ і templates/plugins/ переносяться з попередньої версії в нову — інакше після оновлення вітрина втратила б блоки встановлених доповнень.

Що переживає оновлення, а що ні#

Налаштування теми переживають. Вони лежать у вітрини в базі, а не у файлах: за збіжними ключами нова версія побачить усе, що власник налаштував.

⚠️ Правки власника у файлах теми втрачаються. Папка замінюється цілком. Скажіть про це в описі теми прямим текстом.

Правильна відповідь власнику, який хоче і змінювати верстку, і отримувати оновлення: він робить копію вашої теми і живе з нею. Копія теми незалежна — правки в ній у безпеці, але й оновлення оригіналу в неї не приходять. Іншого способу немає: успадкування між темами не існує, копія завжди повна.

Правило автора теми: не перейменовуйте ключі налаштувань#

Перейменували primary_color на primary — власник отримає колір за замовчуванням замість свого і вирішить, що оновлення зламало магазин.

Потрібна нова поведінка — заводьте новий ключ, а старий залишайте працювати. Для нового поля обов'язково задавайте значення за замовчуванням: воно підставиться саме, і після оновлення тема не зустріне власника порожнечею.

Опис теми в маркетплейсі#

Опис говорить, що тема дає магазину, а не як вона влаштована всередині. Обіцяти те, чого в темі немає, не можна — це видно клієнту одразу після покупки.

Пишіть звичайними реченнями, звертаючись до читача на «ви»: «Ви задаєте кольори і ширину просто в панелі, не чіпаючи файли», а не «підтримується налаштування палітри».

Два абзаци: перший — що це за тема і як вона виглядає в роботі; другий — що саме в ній є: які сторінки оформлені, які налаштування доступні, з якими доповненнями вона працює.

Що варто сказати в описі окремо#

• які мови в темі є готовими;
• чи розрахована вона на конкретну товарну нішу;
• що правки у файлах втрачаються під час оновлення і для правок роблять копію;
• якщо тема підключає щось ззовні — прямо про це.

Установлення теми з файлу#

Розділ «Платформа» → «Установлення і оновлення» → «Установлення файлом».

⚠️ Зараз цей екран не доводить установлення до кінця. У файлу з диска немає підпису маркетплейсу, тому магазин вимагає усвідомленого підтвердження власника, а кнопки підтвердження на екрані немає. Завантаження закінчується повідомленням про те, що файл не підписаний.

Саме установлення при цьому справне: воно ставить тему і правильно відмовляє темі, яка вимагає магазин новіший. Поки екран не доробили, тему на чужий магазин кладуть папкою або ставлять з маркетплейсу.