Мы постараемся задокументировать все изменения чтобы вам было легче обновить ваши модули под новую версию JohnCMS

Изменена стандартная структура модуля

Теперь классы модуля должны располагаться в папке src, которая располагается в папке с модулем. Маршруты для работы модуля теперь описываются в папке модуля, а не в общем конфигурационном файле. Файлы конфигурации так же расположены теперь в папке с модулем. Подробнее можете ознакомиться в инструкции по созданию модуля.

Удалено пространство имен Johncms\System

Все классы, которые располагались в пространств Johncms\System были перенесены в пространство имен Johncms. Например:

$request = di(\Johncms\System\Http\Request::class);

$request = di(\Johncms\Http\Request::class);

Все POST запросы должны содержать CSRF-токен

Все POST запросы, проходящие через роутер, теперь по умолчанию проверяются на наличие корректного CSRF токена. Если токена нет, вы будете получать ошибку 419. Токен должен содержаться в поле с именем csrf_token или же в заголовке X-CSRF-Token. Если вы хотите отключить проверку для определенных адресов, то можете добавить исключение в конфигурационном файле. Пример файла config/autoload/csrf.global.php для правильной кастомизации ознакомьтесь с инструкцией по работе с конфигурационными файлами.

Системные требования

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

• Nginx + php-fpm или Apache

• PHP 8.0 и выше

• MySQL 5.7 и выше или MariaDB 10.2 или выше

• Для работы с MуSQL должен использоваться встроенный драйвер MySQL Native Driver (mysqlnd)

Для работы системы требуются следующие расширения php:

• imagick или gd

• mbstring

• pdo

• simplexml

Хостинг должен позволять указать в качестве корневой директории папку public. Обычно хостинги позволяют это сделать. Уточните этот момент у вашего хостинг-провайдера.

Установка

• Скачиваем архив

• Распаковываем архив в папку выше уровня корневой. Таким образом, чтобы корневой папкой была папка public. Как это сделать уточните в поддержке вашего хостинг-провайдера или же на нашем форуме.

• Перейдите на главную страницу вашего сайта (вы будете переадресованы на страницу установки).

• Следуйте инструкциям описанным на странице установки

Установка для разработки

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

Есть несколько вариантов установки системы локально.

1. Установка и настройка локального окружения

2. Установка в Docker (рекомендуется)

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

Данный способ подойдет если вы устанавливаете все окружение самостоятельно. Помимо описанного в системных требованиях программного обеспечения вам потребуется Nodejs, GIT, composer.

Склонируйте или скачайте репозиторий в нужную папку. Например так:

git clone https://github.com/johncms/johncms.git johncms
cd johncms

Установите и настройте окружение так, чтобы корневой папкой домена была папка public в корне проекта, который вы склонировали.

Установите зависимости выполнив поочередно следующие команды в консоли.

composer install
npm install
npm run build

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

Установка в Docker (рекомендуется)

Установка с помощью Docker не требует от вас специальных знаний по настройке окружения. Все что вам потребуется, это Docker и GIT.

Склонируйте или скачайте репозиторий.

git clone https://github.com/johncms/johncms.git johncms
cd johncms

Запустите контейнер (при первом запуске произойдет скачивание и сборка контейнера, а последующие запуски будут происходить быстрее).

make up

docker-compose up -d

Передите в консоль контейнера с помощью следующей команды:

make shell

docker exec -it $(docker ps -q -f name=ubuntu) bash

После того как откроется консоль контейнера выполните следующую команду:

npm install && composer install && npm run build

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

Ваш сайт будет доступен по адресу http://localhost:8000

При установке вам потребуются данные для подключения к БД. Используйте следующие данные:

DB Host: mariadb DB Name: johncms DB User: johncms DB Password: password

Больше никаких настроек выполнять не требуется.

Страница будет актуализирована по мере готовности функционала в JohnCMS 10

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

Ошибка 500.

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

Для включения вывода ошибок откройте файл config/constants.php, найдите строки

Замените false на true

После этих действий на сайте должен отображаться текст ошибки.

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

Драйверы и настройка

На данный момент поддерживаются следующие драйверы: Sendmail, SMTP, File. Этих драйверов обычно более чем достаточно большинству проектов.

Отправка сообщений

Отправка email достаточно затратная операция. Для решения этой проблемы отправку email можно переложить на сервер. Для этого в JohnCMS реализована очередь сообщений. Чтобы отправить письмо, необходимо просто добавить его в очередь.

Рассмотрим пример добавления письма в очередь:

Что делает этот код? Он добавляет запись в таблицу email_messages. А дальше система проверяет наличие не отправленных писем в очереди и отправляет их.

Какие поля необходимы?

• priority - Приоритет отправки сообщения. Чем меньше, тем выше. (не обязательно)

• locale - Поле обязательно и содержит код языка, на котором будет отправлено сообщение.

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

• fields - содержит массив полей, которые будут доступны в шаблоне, а так же будут использоваться для отправки:

  • email_to - E-mail адрес получателя сообщения (обязательное поле)

  • name_to - Имя получателя, которое будет отображаться в почтовом клиенте. (не обязательно)

  • subject - Тема сообщения. (не обязательно, но рекомендуется)

  • Прочие поля доступны только в шаблоне, не требуются для работы драйвера и могут отсутствовать.

Отправка почтовых сообщений по умолчанию выполняется на хитах. Это значит, что для отправки письма какой либо пользователь должен зайти на сайт. В момент на сайт, выполняется проверка наличия неотправленных сообщений и если таковые находятся, выполняется отправка. Этот вариант не всегда подходит, особенно если сообщений отправляется много. По этому рекомендуется перевести отправку сообщений на cron.

Перевод отправки Email на CRON

Для того, чтобы избежать подвисания страницы для пользователей в JohnCMS реализована отправка сообщений с помощью планировщика cron. Если ваш хостинг поддерживает cron, то рекомендуем перевести отправку сообщений на него. Для этого откройте файл: config/constants.php Найдите строчку:

И замените false на true.

Далее необходимо добавить задачу в cron:

php system/cron.php

Периодичность выполнения установить раз в 1 минуту. Обратите внимание, что может потребоваться указать полный путь к файлу от корня. Посмотреть его можно в phpinfo(), параметр DOCUMENT_ROOT или вывести так: echo $_SERVER['DOCUMENT_ROOT']; Более подробно про то как добавить задачу, вы можете уточнить у вашего хостинг провайдера.

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

Начиная с JohnCMS 9.3 в системе появилась поддержка шаблонов для email.

Для чего это нужно?

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

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

Рассмотрим пример письма:

В письмах как и на всем сайте есть основной шаблон, который является общим практически для всех страниц (header/footer. На скриншоте отмечен цифрами 1 и 3). Сам текст письма - это контентная область (на скриншоте отмечена цифрой 2), которая в разных письмах может выглядеть по разному.

Базовых шаблонов может быть несколько и каждый шаблон сообщения может использовать любой базовый шаблон.

Всё это позволит вам менять базовый шаблон не меняя все шаблоны писем. Например, вы можете сделать несколько шаблонов на все времена года, зимний, летний, весенний, осенний и менять их когда это необходимо. При этом вам нужно будет изменить всего 1 файл, а шаблоны писем изменять не придется вовсе.

Где хранятся шаблоны?

Почтовые шаблоны так же как и основные шаблоны сайта хранятся в папке themes.

Основной шаблон расположен в папке themes/default/templates/system/mail/layouts/default.phtml

В этом файле расположен основной макет письма.

Шаблоны конкретных сообщений расположены в папке themes/default/templates/system/mail/templates

Шаблонная система для почтовых сообщений работает так же как и шаблоны основного сайта. Поддерживается возможность переопределения и все прочие возможности. Для кастомизации системных шаблонов копируйте их в папку с собственным шаблоном. Таким образом вам не придется переносить изменения при обновлении CMS.

Наверное Вы уже задавались вопросом "Где хранятся настройки JohnCMS и как добавлять свои настройки?". Давайте рассмотрим подробнее.

Когда мы открываем папку config, то видим в ней примерно такую структуру:

Файлов достаточно много, давайте разберёмся за что они отвечают.

Файлы в директории autoload:

Директория autoload содержит все конфигурационные файлы, которые автоматически загружаются системой. Как вы наверное заметили есть файлы содержащие в названии global и local. Файлы global это обычно файлы, которые могут обновляться при выходе новых версий JohnCMS. Не рекомендуем их редактировать, т.к. это осложнит обновление CMS.

Файлы local - это локальные файлы конкретно для вашего сайта. Они не содержаться в дистрибутиве JohnCMS. Некоторые из них создаются автоматически при установке системы, а некоторые вы можете создавать вручную.

Как же быть если вы хотите изменить какие-то параметры, которые есть в global файле?

Всё очень просто. Нужно создать файл с таким же названием, но заменить global на local.

Например, вы хотите изменить настройки в файле mail.global.php, для этого скопируйте этот файл и сохраните под именем mail.local.php. Далее измените в нем нужные параметры и они переопределят те параметры, которые уже содержатся в mail.global.php.

Давайте рассмотрим пример:

Содержимое mail.global.php

Допустим нам нужно изменить имя пользователя: username. Это можно сделать так:

Содержимое файла mail.local.php

Давайте теперь получим итоговый результат.