Главная
Инструкции
Інструкція зі створення репозиторію модулів для OkayCMS

Інструкція зі створення репозиторію модулів для OkayCMS

Содержание

Категории

Что нужно сделать сначала

Marketplace start

Перед тем как приступать к публикации модулей, необходимо пройти несколько подготовительных этапов.

Убедитесь, что вы уже:

Ознакомились с преимуществами партнёрской программы OkayCMS
Ознакомились с условиями и правилами сотрудничества
Подали заявку на партнёрство через официальный сайт OkayCMS
Получили обратную связь от службы поддержки
Зарегистрировались в маркетплейсе в качестве партнёра

После выполнения этих шагов вы получите доступ к кабинету партнёра и сможете переходить к подготовке и публикации модулей.

Далее в этой инструкции рассмотрим полный процесс: от подготовки репозитория до появления модуля в маркетплейсе OkayCMS.

Как работает публикация модулей

Ниже показана общая схема публикации модулей в OkayCMS.

Процесс начинается с чистой версии OkayCMS, после чего для каждого модуля создаётся отдельная ветка. В этой ветке выполняется вся разработка и внесение изменений. После завершения работы создаётся версия модуля через Git tag, а маркетплейс автоматически получает новую версию из репозитория.

master. Чистая версия OkayCMS без сторонних модулей и изменений. Используется как база для создания новых модулей.
Создание ветки модуля. Для каждого нового модуля создаётся отдельная Git-ветка. В ней хранится весь код, относящийся только к этому модулю.
Разработка модуля. Этап создания функционала, логики работы, шаблонов, настроек и необходимых файлов модуля.
Commit. Фиксация выполненных изменений в Git с кратким описанием проделанной работы.
Git tag. Создание отдельной версии модуля. Именно Git tag используется маркетплейсом для создания новой версии.
Bitbucket. Репозиторий, в котором хранится код модуля, история изменений и все его версии.
modules.okay-cms.com. Сервис автоматически проверяет репозиторий, находит новые теги и импортирует новые версии модулей.
Маркетплейс OkayCMS. После обработки модуль или его новая версия становится доступной пользователям в маркетплейсе.

Важно:

✅ Один модуль = одна отдельная ветка

✅ Один Git tag = одна отдельная версия модуля

✅ Ветка модуля создаётся от master

❌ Ветки модулей не сливаются обратно в master

Необходимые инструменты и знания

Перед началом работы убедитесь, что у вас подготовлена необходимая рабочая среда и имеются базовые знания для работы с модулями OkayCMS.

Для работы понадобятся:

Инструмент	Для чего нужен
Git	Управление версиями
Bitbucket	Хранение кода и репозиториев
VS Code / PhpStorm	Редактирование кода
Локальная копия OkayCMS	Разработка и тестирование модуля

Необходимые базовые знания:

✅ Работа с Git (commit, push, branch)

✅ Структура OkayCMS

✅ Базовые знания PHP / HTML / JS

✅ Работа с терминалом

Настройка локального окружения

Шаг 1. Клонируйте OkayCMS

Склонируйте официальный репозиторий OkayCMS:

git clone https://github.com/OkayCMS/OkayCMS.git <folder_name>

Например:

git clone https://github.com/OkayCMS/OkayCMS.git okay_modules

Или, если вы уже находитесь в нужной пустой папке:

git clone https://github.com/OkayCMS/OkayCMS.git .

Точка означает клонирование репозитория в текущую директорию.

Шаг 2. Удалите историю Git

Перейдите в директорию проекта:

cd <folder_name>

После этого выполните:

rm -rf .git

Это отвяжет репозиторий от официальной истории OkayCMS.

Шаг 3. Инициализируйте новый репозиторий

git init

После выполнения будет создана директория .git.

Важно: без этого шага команды git add, git commit и git push работать не будут.

Шаг 4. Создайте локальный конфиг

Создайте файл:

config/config.local.php

Пример:

<?php $config = [ 'db_host' => 'localhost', 'db_user' => 'root', 'db_pass' => '', 'db_name' => 'okaycms', ];

Файл используется для подключения локальной базы данных.

Шаг 5. Импортируйте базу данных

Импортируйте файл:

1DB_changes/okay_clean.sql

Для импорта можно использовать phpMyAdmin, Adminer или TablePlus.

Шаг 6. Установите зависимости

composer install

Команда установит все необходимые библиотеки для работы OkayCMS.

Создание и подключение репозитория Bitbucket

После подготовки локального окружения необходимо создать собственный репозиторий в Bitbucket. Именно он будет использоваться для хранения кода модулей, ведения истории изменений и автоматической интеграции с маркетплейсом OkayCMS.

При создании репозитория важно сразу указать правильные параметры. Неверные настройки на этом этапе могут привести к проблемам с Git, webhook или автоматическим импортом модулей в маркетплейс.

На этом этапе вы:

Создадите новый репозиторий в Bitbucket
Настроите его начальные параметры
Укажете правильную основную ветку
Подключите локальный проект к репозиторию
Подготовите репозиторий к дальнейшей разработке и публикации модулей

Особое внимание обратите на ветку master.

В репозитории OkayCMS ветка master используется как база для создания модулей и должна содержать только чистую версию OkayCMS без сторонних изменений, тестового кода и файлов модулей.

Именно от ветки master в дальнейшем будут создаваться отдельные ветки модулей, поэтому при создании репозитория необходимо использовать:

Default branch → master

Не рекомендуется использовать ветку main, поскольку документация, процесс публикации модулей и механизмы обновления в OkayCMS ориентированы именно на master.

Параметры репозитория должны быть следующими:

Include README → No
Include .gitignore → No
Default branch → master

README и .gitignore создавать не нужно, так как они уже присутствуют в исходном коде проекта или будут добавлены позже при необходимости.

Подключение локального проекта к репозиторию

После создания репозитория необходимо привязать к нему локальный проект. Для этого нужно добавить удалённый репозиторий origin.

Если используется SSH:

git remote add origin [email protected]:<workspace>/<repository>.git

Или через HTTPS:

git remote add origin https://<login>@bitbucket.org/<workspace>/<repository>.git

Проверить подключение можно командой:

git remote -v

После этого локальный проект будет связан с репозиторием Bitbucket, и вы сможете выполнять git push, создавать Git tag и публиковать новые версии модулей.

Важно:

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

После завершения этого шага репозиторий будет создан, локальный проект будет подключён к Bitbucket, и вы сможете перейти к первому commit чистой версии OkayCMS.

Первый commit чистой версии OkayCMS

После создания репозитория в Bitbucket необходимо добавить в него чистую версию OkayCMS и выполнить первый commit в ветку master.

Этот шаг является основой для дальнейшей разработки модулей, поскольку именно от этого состояния репозитория в будущем будут создаваться отдельные ветки модулей.

Выполните команды:

git add . git commit -m "OkayCMS 4.5.2" git push -u origin master

На этом этапе вы:

Добавите все файлы OkayCMS в Git
Создадите первый commit с чистой версией системы
Отправите код в репозиторий Bitbucket
Создадите базовую ветку master для дальнейшей разработки модулей

Зачем это нужно?

В ветке master должна храниться только чистая версия OkayCMS без каких-либо изменений и дополнительных файлов. Именно от неё в дальнейшем будут создаваться отдельные ветки модулей.

Важно: в ветке master не должно быть:

❌ файлов модулей;

❌ тестового кода;

❌ демо-контента;

❌ временных файлов разработки.

После выполнения команд рекомендуется проверить репозиторий в Bitbucket и убедиться, что в нём находится только чистая структура файлов OkayCMS.

После завершения этого шага репозиторий будет готов к созданию первой ветки модуля.

Создание ветки модуля

В OkayCMS каждый модуль разрабатывается в отдельной Git-ветке, которая создаётся от ветки master. Такой подход позволяет изолировать код разных модулей, упрощает поддержку проекта и исключает случайное попадание кода модуля в основную ветку системы.

Перед созданием новой ветки убедитесь, что вы находитесь в ветке master:

git checkout master

После этого создайте новую ветку для модуля:

git checkout -b popup_cart

Где popup_cart — это название вашего модуля и будущей ветки.

На этом этапе вы:

Перейдёте в чистую ветку master
Создадите отдельную ветку для нового модуля
Подготовите окружение для дальнейшей разработки
Отделите код модуля от других проектов и модулей

Примеры названий веток:

popup_cart — всплывающая корзина;
set — комплекты товаров;
fast_order — быстрый заказ.

Зачем это нужно?

Каждый модуль в маркетплейсе OkayCMS должен иметь собственную отдельную ветку. Это позволяет независимо разрабатывать, обновлять и публиковать модули без влияния на другие ветки репозитория.

Важно:

ветка модуля всегда создаётся от master;
одна ветка = один модуль;
ветки модулей не сливаются обратно в master;
в ветке master должна оставаться только чистая версия OkayCMS.

После создания ветки можно переходить непосредственно к разработке модуля и добавлению его файлов в структуру OkayCMS.

Структура файлов модуля

Все файлы модуля должны размещаться исключительно внутри каталога:

Okay/Modules/<Vendor>/<ModuleName>/

Например:

Okay/Modules/VendorName/PopupCart/ Okay/Modules/Partner/PopupCart/

Именно такая структура используется в OkayCMS и поддерживается маркетплейсом при проверке, импорте и установке модулей.

На этом этапе вы:

Создадите правильную структуру каталогов для модуля
Отделите файлы модуля от ядра OkayCMS
Обеспечите совместимость с маркетплейсом
Подготовите модуль к дальнейшей разработке и публикации

Зачем это нужно?

Размещение всех файлов модуля в каталоге Okay/Modules позволяет:

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

Правильное расположение файлов:

Все файлы, шаблоны, настройки, контроллеры, сущности и служебные файлы модуля должны находиться только внутри каталога:

Okay/Modules/<Vendor>/<ModuleName>/

Не рекомендуется размещать файлы модуля:

❌ В каталоге backend;

❌ В каталоге design;

❌ В корне проекта;

❌ В каталоге files или любых других системных каталогах.

Такое размещение нарушает структуру проекта, усложняет поддержку модуля и может привести к ошибкам при обновлении системы.

Важно:

все файлы модуля должны быть изолированы внутри каталога Okay/Modules;
один модуль = один отдельный каталог;
не рекомендуется вносить изменения в ядро OkayCMS для реализации функционала модуля;
структура модуля должна соответствовать стандартам OkayCMS.

Соблюдение структуры Okay/Modules/<Vendor>/<ModuleName>/ является стандартом разработки модулей для OkayCMS и обеспечивает их корректную работу в маркетплейсе.

Версия модуля

Каждый модуль должен содержать информацию о своей текущей версии. Для этого используется файл module.json, который находится в каталоге инициализации модуля.

Файл должен находиться по пути:

Okay/Modules/<Vendor>/<ModuleName>/Init/module.json

Пример содержимого файла:

{ "version": "1.0.0" }

На этом этапе вы:

укажете текущую версию модуля
подготовите модуль к публикации в маркетплейсе
настроите корректное отслеживание релизов
обеспечите совместимость с механизмом обновлений OkayCMS

Зачем это нужно?

Маркетплейс OkayCMS использует версию из файла module.json для определения текущего релиза модуля. Во время импорта маркетплейс проверяет соответствие версии и Git tag.

Важно:

Значение поля version в файле module.json должно полностью совпадать с версией, используемой в Git tag.

Правильно:

module.json { "version": "1.0.0" } Git tag popup_cart_1.0.0

Неправильно:

module.json { "version": "1.0.0" } Git tag popup_cart_0.9.9

module.json { "version": "1.0.0" } Git tag popup_cart_1.0.1

Формат Git tag является обязательным:

<branch_name>_<version>

Например:

popup_cart_1.0.0

Не рекомендуется использовать:

1.0.0
v1.0.0
master_1.0.0

Другие форматы тегов не поддерживаются маркетплейсом OkayCMS.

После настройки версии можно переходить к созданию первого релиза модуля и публикации Git tag.

Правила ведения версионирования

Для версионирования модулей в OkayCMS используется формат:

MAJOR.MINOR.PATCH

Например:

1.0.0

Каждая цифра в версии имеет своё назначение и изменяется в зависимости от типа внесённых изменений.

Ситуация	Что изменяется	Пример
Исправление ошибки	третья цифра (PATCH)	1.0.0 → 1.0.1
Новая логика или функционал	вторая цифра (MINOR)	1.0.1 → 1.1.0
Полная переработка	первая цифра (MAJOR)	1.1.0 → 2.0.0

Пример развития версии:

1.0.0 → 1.0.1 → 1.0.2 → 1.1.0 → 1.2.0 → 2.0.0

Важно: версия в файле module.json должна совпадать с версией Git tag.

{ "version": "1.1.0" } popup_cart_1.1.0

Если версии не совпадают, маркетплейс не сможет корректно определить новый релиз модуля.

Публикация модуля в репозиторий

После завершения разработки модуль необходимо опубликовать в репозитории и создать Git tag. Именно Git tag используется маркетплейсом OkayCMS для определения новой версии модуля и её автоматического импорта.

Процесс публикации состоит из двух шагов:

Сохранение изменений в Git (commit).
Создание Git tag для новой версии модуля.

Шаг 1. Создайте commit

После завершения разработки добавьте все изменения в Git и создайте commit в ветке модуля.

git add . git commit -m "Первая версия" git push origin popup_cart

После выполнения этих команд код модуля будет сохранён и отправлен в репозиторий Bitbucket.

Шаг 2. Создайте Git tag

После публикации кода необходимо создать тег версии. Для первого релиза это обычно версия 1.0.0.

git tag popup_cart_1.0.0 git push origin popup_cart_1.0.0

После отправки тега Bitbucket передаст информацию через Webhook, а маркетплейс автоматически импортирует новую версию модуля.

Важно:

✅ Версия в module.json должна совпадать с версией Git tag;

✅ Каждая новая версия должна иметь новый Git tag;

✅ Формат тега должен быть <branch_name>_<version>;

❌ Не изменяйте уже опубликованные теги;

Например:

popup_cart_1.0.0 popup_cart_1.1.0 popup_cart_1.2.0

После создания Git tag новая версия модуля автоматически появится в маркетплейсе OkayCMS.

Обновление OkayCMS в модуле

Во время разработки модуля в ветке могут накапливаться изменения из основной ветки master. Чтобы получать новые обновления ядра OkayCMS, необходимо выполнять обновление через Git merge.

Все работы над модулем выполняются только в его собственной ветке.

Сначала перейдите в ветку модуля:

git checkout popup_cart

После этого выполните merge из ветки master:

git merge master

На этом этапе вы:

Получите последние изменения из чистой версии OkayCMS;
Обновите свою ветку модуля;
Сохраните собственные изменения модуля;
Обеспечите совместимость с текущей версией OkayCMS.

Как это работает?

После выполнения git merge master в вашу ветку попадут последние изменения из master, при этом сам модуль останется в своей ветке и продолжит развиваться независимо.

Зачем использовать merge?:

✅ Сохраняется история изменений;

✅ Легко отслеживать обновления OkayCMS;

✅ Снижается риск конфликтов;

✅ Гарантируется совместимость с текущей версией системы.

Нельзя:

❌ Копировать файлы OkayCMS вручную;

❌ Обновлять ядро напрямую в ветке модуля;

❌ Заменять файлы системы вручную.

Такие действия могут привести к конфликтам, потере изменений или проблемам при дальнейших обновлениях.

Важно:

Обновление OkayCMS в модуле всегда выполняется только через git merge master. Это стандартный и рекомендуемый способ поддерживать модуль в актуальном состоянии.

Демо-контент

Если модуль требует демонстрационных данных, их необходимо добавлять в отдельный файл:

1DB_changes/demo.sql

Этот файл используется для импорта демо-контента при установке или тестировании модуля.

На этом этапе вы:

подготовите демонстрационные данные для модуля;
упростите тестирование функционала;
покажете возможности модуля на тестовом сайте;
сохраните совместимость с системой и маркетплейсом.

Используйте только: 1DB_changes/demo.sql

Не используйте: 1DB_changes/okay_clean.sql

Файл okay_clean.sql используется для развёртывания чистой системы OkayCMS и не предназначен для хранения демонстрационных данных модуля.

В demo.sql разрешается добавлять:

✅ Товары;

✅ Баннеры;

✅ Категории;

✅ Страницы;

✅ Изображения и связанные с ними данные.

Нельзя добавлять или изменять:

❌ ok_managers — пользователи и права доступа;

❌ ok_settings — настройки системы;

❌ ok_modules — список установленных модулей.

Зачем нужен отдельный файл demo.sql?

добавляет демонстрационные данные для модуля;
безопасен для импорта на тестовых сайтах;
не влияет на настройки OkayCMS;
легко удаляется вместе с модулем.

Важно:

Демонстрационные данные должны быть безопасны для импорта и не изменять системные настройки OkayCMS. Используйте реалистичные примеры данных, чтобы пользователь мог быстро оценить возможности вашего модуля.

README для пользователя

Для каждого модуля рекомендуется создавать файл README.md. Это основная документация для пользователя, которая помогает быстро установить, настроить и использовать модуль.

Файл рекомендуется размещать по пути:

Okay/Modules/<Vendor>/<ModuleName>/README.md

На этом этапе вы:

подготовите документацию для пользователей;
упростите установку модуля;
уменьшите количество обращений в поддержку;
повысите удобство использования модуля.

В README рекомендуется описать:

процесс установки;
настройку модуля;
необходимые изменения шаблона (если они требуются);
основные параметры и возможности модуля.

Пример структуры README:

Установка
Настройка
Необходимые изменения шаблона
Дополнительная информация

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

Рекомендации:

✅ Пишите простым и понятным языком;

✅ Добавляйте примеры кода там, где это необходимо;

✅ Описывайте только то, что действительно нужно пользователю для работы с модулем;

✅ Обновляйте README при добавлении нового функционала.

Качественный файл README.md значительно упрощает установку и настройку модуля для конечного пользователя.

Подключение маркетплейса

После создания репозитория необходимо предоставить маркетплейсу доступ к нему и настроить автоматическое получение обновлений. Для этого нужно добавить SSH-ключ и Webhook, данные для которых доступны в вашем кабинете на modules.

Шаг 1. Добавьте SSH-ключ

В Bitbucket откройте:

Repository settings → Access keys

Добавьте SSH-ключ, указанный в вашем кабинете на modules.

SSH-ключ используется для предоставления маркетплейсу доступа к вашему репозиторию и загрузки файлов модуля.

Шаг 2. Настройте Webhook

В Bitbucket откройте:

Repository settings → Webhooks

Добавьте Webhook URL, указанный в вашем кабинете на modules.

После каждого создания Git tag или отправки изменений в репозиторий Bitbucket будет автоматически уведомлять маркетплейс об обновлениях.

Что происходит после настройки?

После создания нового Git tag маркетплейс автоматически:

получает уведомление от Bitbucket;
загружает новую версию модуля из репозитория;
обновляет информацию о модуле;
публикует новую версию в маркетплейсе.

Схема работы:

Git tag ↓ Bitbucket ↓ Webhook ↓ Marketplace OkayCMS ↓ Новая версия модуля

Важно:

✅ Используйте только SSH-ключ из вашего кабинета на modules;

✅ Используйте только Webhook URL из вашего кабинета на modules;

✅ Webhook должен быть активирован;

✅ Репозиторий должен содержать ветку master.

Без настроенных SSH-ключа и Webhook маркетплейс не сможет автоматически получать изменения из вашего репозитория и публиковать новые версии модулей.

Что поможет избежать ошибок

При первой публикации модулей разработчики часто допускают одни и те же ошибки. Большинство из них приводят к проблемам с импортом модуля, созданием новых версий или автоматической работой маркетплейса.

Самые распространённые ошибки:

❌ Создана ветка main вместо master;

❌ Git tag создан до commit или до отправки изменений в репозиторий;

❌ Версия в module.json не совпадает с версией Git tag;

❌ Файлы модуля попали в ветку master;

❌ SSH-ключ добавлен не в тот репозиторий;

❌ Webhook открывается вручную в браузере вместо автоматического вызова Bitbucket;

❌ Файл demo.sql добавлен в master вместо ветки модуля.

В большинстве случаев такие ошибки можно обнаружить ещё до публикации первой версии модуля.

Полезная рекомендация.

Если вы публикуете модуль впервые, рекомендуется выполнить несколько дополнительных проверок:

✅ Создать тестовую копию сайта;

✅ Проверить установку модуля из архива;

✅ Проверить обновление через Git tag;

✅ Убедиться, что README содержит инструкцию по установке и настройке.

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