Документация

Требования к серверу

Кобза рассчитана на самый обычный хостинг. Ни Composer, ни Node, ни доступа к консоли не нужно — достаточно FTP или файлового менеджера в панели управления.

Без mbstring система работает, но кириллицу обрабатывает запасным путём — чуть медленнее. Без GD не определяются размеры изображений: на вёрстку это не влияет.

Установка

1. Распакуйте архив в корень сайта. Обычно это папка public_html, www или httpdocs. Файлы должны лежать в ней, а не в подпапке — иначе сайт откроется по адресу вида site.ru/kobza/.
2. Дайте права на запись папке storage. В файловом менеджере хостинга это «права доступа» или «CHMOD», значение 775. Туда система кладёт базу и загруженные файлы.
3. Откройте адрес сайта в браузере. Установщик встретит сам. Если не открылся — зайдите напрямую на /install.php.
4. Пройдите пять шагов. Проверка сервера, выбор базы, лицензия или пробный период, администратор, готово.
5. Удалите файл install.php. Пока он на сервере, установщик доступен всем.

Какую базу выбрать

SQLite подходит для сайта учреждения с запасом. База — один файл в папке storage, настраивать нечего, переносится копированием. Берите её, если сомневаетесь.

MySQL выбирайте, если база уже заведена на хостинге, если сайт обещает быть очень посещаемым или если хостер делает автоматические резервные копии баз, а вы хотите ими пользоваться. Кодировка базы — utf8mb4, таблицы установщик создаст сам.

Что создаётся при установке: раздел «Новости», главная страница и пример новости. Это заготовка, чтобы было понятно, как система устроена, — переписывайте или удаляйте.

Настройка nginx

На Apache правила уже лежат в файле .htaccess, ничего делать не нужно. Для nginx добавьте в конфигурацию сайта:

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

location ~ ^/(core|storage)/ {
    deny all;
}

location ^~ /storage/uploads/ {
    allow all;
    location ~ \.php$ { deny all; }
}

location = /config.php { deny all; }

Смысл правил: все адреса уходят на точку входа, служебные папки закрыты, а загруженные файлы отдаются, но не исполняются.

Первые шаги после установки

Панель управления — по адресу /admin/. Разумный порядок работы:

1. Настройки. Название сайта, подпись, контакты, адрес почты для обращений, акцентный цвет. Проверьте, включена ли версия для слабовидящих — для учреждения она обязательна.
2. Разделы. Сначала структура: «О нас», «Документы», «Новости», «Контакты». Адреса страниц складываются из пути раздела, поэтому структуру лучше продумать до наполнения.
3. Файлы. Загрузите логотип и документы заранее — в редакторе они будут под рукой.
4. Страницы. Создайте страницу, укажите раздел и откройте редактор.
5. Главная. Отметьте нужную страницу как главную в её свойствах.

Черновики видны только тем, кто вошёл в панель. Можно спокойно собирать страницу неделю — посетители её не увидят, пока не поставите галочку «Опубликована».

Ввод лицензионного ключа

Панель управления → «Лицензия» → вставьте ключ из личного кабинета и нажмите «Активировать».

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

Регистр букв не важен, дефисы можно не ставить. Частые опечатки при ручном вводе система исправляет сама: единицу вместо «I», ноль вместо «O». Но надёжнее скопировать ключ целиком из кабинета.

Структура файлов

index.php          точка входа публичной части
install.php        установщик (удалить после установки)
config.php         создаётся установщиком

core/              ядро системы
blocks/            блоки страницы, по папке на блок
admin/             панель управления
themes/default/    оформление публичной части
assets/admin/      стили и скрипты панели
storage/uploads/   загруженные файлы

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

Свой блок

Блок — это папка в blocks/ с двумя файлами. Регистрировать его нигде не нужно: положили папку — блок появился в палитре редактора.

Файл block.json — какие у блока поля

{
  "name": "alert",
  "title": "Важное объявление",
  "group": "Контент",
  "icon": "text",
  "fields": [
    { "key": "text", "type": "rich", "label": "Текст" },
    { "key": "kind", "type": "select", "label": "Вид", "default": "info",
      "options": [
        { "value": "info", "label": "Обычное" },
        { "value": "warn", "label": "Внимание" }
      ] }
  ]
}

Файл template.php — как блок выводится

<section class="kb-sec">
  <div class="kb-wrap">
    <div class="kb-alert kb-alert--<?= K::e($props['kind']) ?>">
      <?= $props['text'] ?>
    </div>
  </div>
</section>

Панель свойств редактор построит из fields сам.

Типы полей

Контейнерные блоки объявляют slots — тогда внутрь можно вкладывать другие блоки, а в шаблон они приходят готовым HTML в переменной $slots.

Внутри шаблона доступны: $props — свойства блока, $slots — отрисованные слоты, $ctx['page'] — текущая страница. Полезные помощники: K::e() — экранирование, K::media() — адрес файла, K::date() — дата по-русски, K::size() — размер файла.

Резервные копии и перенос

Для полной копии нужны две вещи: база и папка storage/uploads.

# SQLite — всё в одном архиве
tar czf backup.tar.gz storage/ config.php

# MySQL — база отдельно
mysqldump -u ПОЛЬЗОВАТЕЛЬ -p БАЗА > dump.sql
tar czf files.tar.gz storage/uploads/ config.php

Перенос на другой хостинг — копирование файлов целиком. Путь к базе SQLite в конфиге относительный, править ничего не нужно. При переезде на MySQL поправьте config.php и восстановите дамп.

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

Обновление

1. Сделайте резервную копию.
2. Скачайте новую версию в личном кабинете.
3. Замените папки core, admin, assets и файл index.php.
4. Не трогайте config.php, storage и свои изменения в themes и blocks.
5. Откройте панель управления — при необходимости схема базы обновится сама.

Установщик заново запускать не нужно, содержимое сайта не затрагивается.

Если что-то не так

Вместо сайта показывается код PHP

Сервер не обрабатывает PHP. Проверьте: файлы лежат в публичной папке, в панели хостинга выбрана версия PHP, а адрес в браузере начинается с домена, а не с file:///.

Ошибка прав при установке

Папке storage и корню сайта нужны права на запись. В файловом менеджере хостинга поставьте 775 на папку. Если не помогает, напишите в поддержку хостинга — иногда мешает владелец файлов.

Открывается только главная, остальные страницы дают 404

Не работают человеческие адреса. На Apache проверьте, что файл .htaccess залился (он скрытый, менеджеры часто его прячут) и что включён mod_rewrite. На nginx добавьте правила из раздела выше. Если сайт лежит в подкаталоге, раскомментируйте в .htaccess строку RewriteBase и укажите путь.

Не приходят письма с обращениями

Проверьте адрес в настройках и уточните у хостера, разрешена ли отправка почты функцией mail(). Сами обращения при этом не теряются: они всегда сохраняются в разделе «Обращения».

Не загружается большой файл

Предел ставит сервер, а не система. Посмотрите значение upload_max_filesize на первом шаге установщика и увеличьте его в настройках PHP на хостинге.

Ключ не принимается

Скопируйте его из кабинета целиком, без лишних пробелов. Если не помогает, напишите нам номер счёта — проверим ключ на своей стороне.