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

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

Мы постараемся задокументировать все изменения чтобы вам было легче обновить ваши модули под новую версию 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

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

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

Ошибка 500.

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

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

// Включаем режим отладки
const DEBUG = false;

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

const DEBUG = true;

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

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

В JohnCMS для отправки электронной почты используется библиотека laminas-mail Она позволяет обобщить отправку сообщений и легко переключать драйверы через которые будет отправляться письмо. Благодаря этому вы сможете выбрать наиболее подходящий вам метод отправки в зависимости от возможностей вашего хостинга и наличия его ip в спам фильтрах.

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

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

Драйвер по умолчанию и настройки драйвера указываются в конфигурационном файле config/autoload/mail.global.php. По умолчанию установлен sendmail, но вы можете сменить драйвер на smtp или file. Примеры настроек есть в указанном файле. Вы можете просто их переопределить. Как это сделать, а так же про работу с конфигурационными файлами рекомендуем прочитать здесь: Конфигурационные файлы.

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

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

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

(new \Johncms\Mail\EmailMessage())->create(
    [
        'locale'   => 'ru',
        'template' => 'system::mail/templates/registration',
        'fields'   => [
            'email_to'        => 'user@example.com',
            'name_to'         => 'Имя Пользователя',
            'subject'         => 'Регистрация на сайте',
            'user_name'       => 'UserName',
            'user_login'      => 'UserLogin',
            'link_to_confirm' => 'https://johncms.com',
        ],
    ]
);

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

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

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

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

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

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

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

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

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

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

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

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

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

const USE_CRON = false;

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

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

php system/cron.php

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

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

JohnCMS имеет следующую структуру папок:

• config

• data

• docker

• modules

• public

• system

• tests

• themes

config

В папке хранятся различные конфигурационные файлы необходимые для работы системы. Файл constants.php содержит константы необходимые для работы системы. В подпапке autoload хранятся файлы, которые автоматически загружаются системой. Работа с конфигурационными файлами подробно описана здесь: Конфигурационные файлы.

data

В папке data хранятся различные системные данные, такие как кэш, временные файлы и логи

docker

В этой папке хранятся файлы конфигурации для запуска сайта в docker контейнере.

modules

Папка modules содержит все модули системы Подробно про структуру папки модуля читайте в соответствующем разделе.

public

Корневая директория проекта в которую должен ссылаться web-сервер. Для обеспечения безопасности, все системные папки располагаются выше публичной директории. В папке public должны содержаться только файлы, которые будут доступны из браузера.

system

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

tests

Папка tests содержит автоматические тесты системы. Используется только при разработке.

themes

Папка themes содержит шаблоны сайта В этой папке расположен шаблон default в папке с этим шаблоном не рекомендуется ничего менять для сохранения возможности простого обновления на следующие версии JohnCMS Для кастомизации шаблона создайте отдельную папку и скопируйте в неё содержимое папки default. Более подробно про работу с шаблонами читайте в соответствующем разделе документации

Этот валидатор позволяет вам проверить, является ли данное значение не пустым. Это часто полезно при работе с элементами формы или другим пользовательским вводом. Вы можете использовать этот валидатор, чтобы убедиться, что пользователь заполнил поле и оно не пустое.

По умолчанию этот валидатор работает иначе, чем вы ожидаете, работая с PHP функцией empty(). В частности, этот валидатор будет оценивать как целое число 0, так и строку «0» как пустые.

Вам может не подойти это поведение и, например, в вашем случае 0 не должен считаться пустым. Для таких случаев в валидаторе NotEmpty вы можете задать некоторые настройки.

Поддерживаемые параметры

• type: Устанавливает тип проверки, которая будет выполнена.

Обрабатываемые типы

• boolean: Возвращает false, когда логическое значение равно false.

• integer: Возвращает false, когда задано целое число 0. По умолчанию эта проверка не активирована и возвращает true для любых целочисленных значений.

• float: Возвращает false, когда задано значение с плавающей запятой 0.0. По умолчанию эта проверка не активирована и возвращает true для любых значений с плавающей запятой.

• string: Возвращает false, когда задана пустая строка.

• zero: Возвращает false, когда задан один символ ноль ('0').

• empty_array: Возвращает false, когда задан пустой массив.

• null: Возвращает false, когда задано значение null.

• php: Возвращает false везде, где PHP empty () возвращает true.

• space: Возвращает false, если задана строка, содержащая только пробел.

• object: Возвращает true. false будет возвращено, когда объект не разрешен, но объект задан.

• object_string: Возвращает false, когда объект задан, а его метод __toString () возвращает пустую строку.

• object_count: Возвращает false, когда объект задан, он реализует Countable, и его количество равно 0.

• all: Возвращает false для всех вышеперечисленных типов.

Рассмотрим пример как передавать эти параметры в валидатор.

Примеры использования

Как видите, для валидатора NotEmpty задан массив настроек, в нем передается параметр type со значениями из списка выше (обрабатываемые типы).

Начиная с 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. Теперь рассмотрим, что и за что отвечает...

Когда мы открываем папку 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

return [
    'mail' => [
        // Default transport (can be sendmail, smtp, file or memory)
        'transport' => 'sendmail',

        // Transport settings
        'options'   => [
            'smtp' => [
                'name'              => 'localhost.localdomain',
                'host'              => '127.0.0.1',
                'connection_class'  => 'plain',
                'connection_config' => [
                    'username' => 'user',
                    'password' => 'pass',
                ],
            ],
            'file' => [
                'path'     => DATA_PATH . 'mail/',
                'callback' => static function (FileTransport $transport) {
                    return 'Message_' . microtime(true) . '_' . mt_rand() . '.txt';
                },
            ],
        ],
    ],
];

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

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

return [
    'mail' => [
        // Transport settings
        'options'   => [
            'smtp' => [
                'connection_config' => [
                    'username' => 'my_user',
                ],
            ],
        ],
    ],
];

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

Чтобы получить содержимое файла mail, выполним следующий код:

d($config['mail']);

Это вернет следующий результат:

Array
(
    [transport] => sendmail
    [options] => Array
        (
            [smtp] => Array
                (
                    [name] => localhost.localdomain
                    [host] => 127.0.0.1
                    [connection_class] => plain
                    [connection_config] => Array
                        (
                            [username] => my_user
                            [password] => pass
                        )
                )
            [file] => Array
                (
                    [path] => /Users/maksim/MyProjects/johncms_public/data/mail/
                    [callback] => Closure Object
                        (
                            [parameter] => Array
                                (
                                    [$transport] => 
                                )
                        )
                )
        )
)

Как видите, в итоговом результате username переопределился тем, что мы указали в файле mail.local.php

Вы можете самостоятельно поэкспериментировать, создать свой конфигурационный файл (global/local), а так же можете переопределить настройки из других файлов.

Для удобства можете создать файл test.php в корне вашего сайта со следующим содержимым:

<?php

require 'system/bootstrap.php';
$config = di('config');

// Выведем содержимое конфига mail
d($config['mail']);

После этого в браузере перейдите по адресу site.com/test.php и увидите результат. (site.com необходимо заменить на адрес вашего сайта).

Autoload рассмотрели, теперь кратко рассмотрим остальные файлы.

Прочие конфигурационные файлы:

constants.php - Файл содержит различные константы. В нем вам скорее всего понадобятся константы USE_CRON (для перевода отправки email на cron) и DEBUG для включения режима отладки при возникновении ошибок или при разработке модулей.

notifications.global.php - Этот файл содержит шаблоны уведомлений. Параметры в данном файле можно переопределить или дополнить с помощью файла notifications.local.php

places.global.php - Файл содержит информацию о местоположении пользователей. Параметры в данном файле можно переопределить или дополнить с помощью файла places.local.php

routes.php - файл для настройки маршрутизации. Подробно работу с ним мы рассматривали в этой статье: Маршрутизация (роутинг)

Работать с датами в PHP довольно просто, но когда дело доходит до работы с часовыми поясами всё становится не так просто.

Чтобы было проще работать с датами и временем в JohnCMS достаточно придерживаться простых правил:

• Все даты в базе данных должны храниться в UTC

• Все даты при выводе должны выводиться в часовом поясе пользователя

Для упрощения работы в JohnCMS есть несколько вспомогательных методов для работы с датами.

Выводим дату и время в пользовательском формате с учетом его часового пояса:

Выводим дату и время в определенном формате с датой и временем без учета настроек формата пользователя:

Выводим дату и время в упрощенном формате (2 часа назад, 3 секунды назад и т.д.)

А теперь рассмотрим подготовку даты и времени для записи в БД:

Эта вспомогательная функция будет полезна если пользователь где-либо на сайте может указывать дату и время. Т.к. пользователь указывает время в своем часовом поясе, то перед сохранением в БД или куда-либо ещё его необходимо сначала привести к UTC.

Обратите внимание, что стандартные функции php такие как date() и time() будут возвращать дату и время в UTC, по этому если вы используете их при записи в БД, дополнительно менять часовой пояс для них не нужно. Достаточно только при выводе воспользоваться одной из вспомогательных функций выше.

Что такое валидатор и зачем он нужен?

Разработчики модулей создавая модули часто сталкиваются с задачей валидации форм, которые отправляет пользователь. Например, практически в любой форме есть поля, обязательные для заполнения. Так же есть поля, значения которых нужно проверить на наличие в базе данных, в некоторых полях может находиться файл, размер которого нам нужно проверить, ссылка, правильность которой тоже нужно проверить или же email адрес в котором, например, нужно проверить не только корректность текста до и после символа @, но и наличие MX записей для указанного домена.

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

Что позволяет делать валидатор?

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

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

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

Здесь массив $data содержит набор данных, которые будут проверяться. Часто это данные из формы, полученные методом POST или GET.

Массив $rules содержит набор правил и их настройку. В качестве ключа указывается название поля из массива $data, а в качестве массива со значениями используется валидатор или набор валидаторов и их настройки. Например в первом правиле проверяется значение поля под названием test, к нему применяется валидатор NotEmpty и StringLength. Валидатор NotEmpty проверяет не пустое ли значение в поле test, а валидатор StringLength проверяет длину значения. В данном случае длина значения должна быть от 6 до 80 символов.

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

Многие популярные валидаторы мы рассмотрим отдельно. Пока можете попробовать выполнить код выше. Для этого в корне вашего сайта создайте файл test.php и вставьте в него этот код. После этого откройте в браузере страницу site.ru/test.php. Вы увидите следующий результат:

Как видно из результата, массив $data не прошел проверку. Валидатор вернул массив полей и правила валидации, которые не прошли проверку. Вы можете изменить в нем значения и понаблюдать за результатом, а так же поэкспериментировать с другими правилами.

Валидатор LessThan позволяет проверить число на предмет того, что оно меньше чем заданное в параметре. Обратите внимание, что данный валидатор работает только с числами. Строки или даты этот валидатор не позволяет проверять.

Поддерживаемые параметры

• inclusive: Включая максимальное значение. Если задано true, то значение равное максимальное значение будет проходить валидацию. Если задано false, то значение равное максимальному значению не будет проходить валидацию.

• max: Устанавливает максимальное значение.

Примеры использования

Этот пример выведет "OK", т.к. включен параметр inclusive и значение равно максимальному.

А этот пример выведет ошибку т.к. параметр inclusive имеет значение false т.к. этот параметр исключает максимальное значение.

Валидатор StringLength позволяет проверить находится ли длина строки в диапазоне заданных значений или нет.

По умолчанию этот валидатор проверяет, находится ли значение между min и max, используя минимальное значение по умолчанию, равное 0, и максимальное значение по умолчанию, равное NULL (то есть неограниченное). Таким образом, без каких-либо опций, валидатор только проверяет, что ввод является строкой.

Поддерживаемые параметры

• encoding: Устанавливает кодировку ICONV в которой будет проверяться строка.

• min: Устанавливает минимально допустимую длину строки.

• max: Устанавливает максимально допустимую длину для строки.

Примеры использования

В указанном примере валидатор проверит строку в кодировке UTF-8 на длину от 3 до 60 символов.

Проверка только минимальной длины:

В этом примере будет проверяться только минимальная длина строки (3 символа). Максимальная будет считаться не ограниченной.

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

В этом же примере будет проверяться только максимальная длина строки. Если строка будет длиннее 50 символов, проверка не пройдет, если менее 50 символов, то проверка пройдет.

Строгое ограничение длины строки:

А в этом примере мы строго ограничили длину строки 6 символами. Т.е. проверка пройдет только если строка будет длиной в 6 символов. Больше или меньше не допускается.

Для работы с данными HTTP запроса в JohnCMS используется класс \Johncms\Http\Request. Он позволяет получить доступ к таким суперглобальным переменным как: $_POST, $_GET, $_COOKIE, $_FILES, $_SERVER. Это позволяет упростить получение значений по умолчанию, и фильтрацию данных, пришедших от пользователя. Давайте посмотрим на примеры.

Для начала необходимо получить объект класса Request.

Строка /** @var \Johncms\Http\Request $request */ не обязательна и служит лишь для работы автодополнения в IDE если вы конечно используете IDE.

Получение данных из $_GET

Предположим, что пользователь открыл страницу http://domain.com/?user_id=123 и нам нужно получить идентификатор пользователя 123. Сделать это можно следующим образом:

Разберем что же тут происходит. Метод getQuery пытается получить user_id из суперглобального массива $_GET. Первым параметром принимает название параметра запроса, вторым параметром можно передать стандартное значение, а третим параметром передается фильтр, с помощью которого будет обработано значение. Вы можете ознакомиться со списком фильтров в официальной документации по этой ссылке:

Коротко что делает строка из примера: Пытается получить параметр GET запроса user_id, если его нет, то возвращает 0, если есть, то очищает и возвращает число. Если передано не число, то вернет значение по умолчанию, то есть 0.

Получение данных из $_POST

Предположим, что отправлена форма, которая содержит user_id и name. Форма отправлена методом POST.

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

Получение данных из $_COOKIE

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

Получение данных из $_SERVER

Этот пример работает так же как и остальные. Получает HTTP_USER_AGENT из суперглобальной переменной $_SERVER.

Получение данных из $_FILES

Этот код вернет массив файлов, в котором каждый элемент будет представлен объектом класса GuzzleHttp\Psr7\UploadedFile. Если вы уже работали с выгрузкой файлов в php, то наверное знаете, что множественные файлы в массиве $_FILES описываются примерно так:

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

Давайте рассмотрим пример сохранения файлов

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

Пример сохранения файлов будет выглядеть так:

В результате отправки формы с файлами, все файлы будут сохранены в папке upload/tmp c оригинальными названиями, с которыми отправил клиент.

Валидатор EmailAddress позволяет выполнить различные проверки email адреса. Валидатор сначала разбивает адрес электронной почты на local-part@hostname и пытается сопоставить их с известными спецификациями для адресов электронной почты и имен хостов.

Поддерживаемые параметры

• allow: Определяет, какой тип доменных имен принимает валидатор. Эта опция используется вместе с опцией hostnameValidator для установки валидатора имени хоста. Возможные значения этой опции определены в константах ALLOW_ * валидатора Hostname:

  • ALLOW_DNS: (по умолчанию) Разрешает доменные имена (например example.com)

  • ALLOW_IP: Разрешает IP адреса.

  • ALLOW_LOCAL: Разрешает локальные домены такие как localhost или www.localdomain

  • ALLOW_URI: Разрешает имена хостов в универсальном синтаксисе URI. См.

  • ALLOW_ALL: Разрешить все типы хостов.

• useDeepMxCheck: Указывает валидатору на необходимость усиленной проверки MX записей домена. Если для этого параметра установлено значение true, то в дополнение к записям MX также используются записи A, A6 и AAAA для проверки того, принимает ли сервер электронную почту. Эта опция по умолчанию имеет значение false.

• useDomainCheck: Определяет, должна ли быть проверена часть домена. Если для этого параметра установлено значение false, будет проверяться только локальная часть адреса электронной почты. В этом случае валидатор имени хоста не будет вызван. Эта опция по умолчанию имеет значение true.

• hostnameValidator: Задает экземпляр объекта валидатора имени хоста, с помощью которого будет проверяться доменная часть адреса электронной почты.

• useMxCheck: Определяет, должны ли быть обнаружены записи MX с сервера. Если для этого параметра задано значение true, то MX-записи используются для проверки того, принимает ли сервер электронную почту или нет. Эта опция по умолчанию имеет значение false.

Пример использования

Рассмотрим наиболее распространенный пример, которого скорее всего вам будет достаточно. Этот пример проверяет существование домена и возможность принимать email. Т.е. выполняется максимально возможная проверка. Она пропустит только точно существующий домен с MX записями.

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

Для работы уведомлений существует таблица в базе данных, которая называется notifications. Она хранит все уведомления для всех пользователей сайта.

Рассмотрим поля, которые доступны в таблице уведомлений:

Принцип работы уведомлений:

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

• Когда пользователь открывает сайт, для него выполняется выборка уведомлений у которых поле read_at = NULL. (т.е. не прочитанные).

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

Добавление уведомлений:

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

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

Этот код добавит уведомление для модуля my_the_best_module и события с типом my_module_event1.

Для чего же нам нужно название модуля и тип события? Это нужно для того, чтобы отображать уведомления в соответствии с заданным шаблоном.

Шаблоны уведомлений:

Шаблоны уведомлений настраиваются в файле config/notifications.local.php. Если у вас нет этого файла, переименуйте файл notifications.local.php.example в notifications.local.php

Файл с шаблонами должен иметь следующую структуру:

Как мы видим, тут используется название модуля и тип события.

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

Как видно на скриншоте, вывелось уведомление с типом my_module_event1. В тексте уведомления заменилась макропеременная #variable# на ту, которую мы подавали при создании уведомления в массиве fields.

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

Пример использования

// Массив полей и значений
$data = [
    'test' => 'token',
];

// Настройки валидатора
$rules = [
    'test' => [
        'Csrf',
        'Flood',
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

В указанном примере валидатор Flood добавлен для того же поля, что и валидатор токена.

Валидатор Ban предназначен для упрощенной проверки наличия банов у пользователя. Валидатор так же обычно используется вместе с валидатором Csrf, т.к. не имеет привязки к данным в форме, но для работы валидатора, он должен быть добавлен для определенного поля.

Поддерживаемые параметры

• bans: Массив банов, наличие которых будет проверяться. Параметр не обязателен. По умолчанию проверяется бан "Полная блокировка".

Пример использования

// Массив полей и значений
$data = [
    'test' => 'token',
];

// Настройки валидатора
$rules = [
    'test' => [
        'Csrf',
        'Flood',
        'Ban' => [11, 13],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

В указанном примере будет проверяться бан для форума (11) и гостевой (13). Если у пользователя есть хотя бы 1 из этих банов, проверка не пройдет.

Валидатор Csrf предназначен для проверки токена csrf. Токен предназначен для защиты формы от подделки запроса. Данный валидатор работает в паре с генератором токенов \Johncms\Security\Csrf

Поддерживаемые параметры

• tokenId: Идентификатор токена. Если не задан, используется токен по умолчанию для всего сайта.

Примеры использования

// Массив полей и значений
$data = [
    'test' => 'token',
];

// Настройки валидатора
$rules = [
    'test' => [
        'Csrf',
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

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

// Массив полей и значений
$data = [
    'test' => 'token',
];

// Настройки валидатора
$rules = [
    'test' => [
        'Csrf' => [
            'tokenId' => 'guestbook_form'
        ],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

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

Более подробно работу с токенами мы рассмотрим в отдельной статье.

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

Для работы этого валидатора вам потребуется существующая модель.

Поддерживаемые параметры

• model: Класс модели, который будет использоваться для построения запроса к БД.

• field: Столбец в БД по которому будет осуществляться поиск записи.

Примеры использования

// Массив полей и значений
$data = [
    'test' => 45,
];

// Настройки валидатора
$rules = [
    'test' => [
        'ModelExists'   => [
            'model' => \Johncms\Users\User::class,
            'field' => 'id',
        ],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

В указанном примере будет выполнена проверка наличия пользователя c идентификатором 45 в таблице users.

Запрос который будет выполнен:

SELECT * FROM `users` WHERE `id` = 45

В результате, если будет найдена запись с id = 45, то валидатор будет считать проверку успешной, если не найдет, то вернёт ошибку.

Рассмотрим ещё один пример:

// Массив полей и значений
$data = [
    'test' => 'admin',
];

// Настройки валидатора
$rules = [
    'test' => [
        'ModelExists'   => [
            'model' => \Johncms\Users\User::class,
            'field' => 'name',
        ],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

В этом примере будет выполнен поиск записи у которой поле name = admin.

Будет выполнен следующий запрос:

SELECT * FROM `users` WHERE `name` = 'admin'

Результат будет такой же как и в случае с id. Если будет найдена строка с полем name = admin, то валидация пройдет успешно, если нет, будет возвращена ошибка.

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

Для работы этого валидатора вам потребуется существующая модель.

Поддерживаемые параметры

• model: Класс модели, который будет использоваться для построения запроса к БД.

• field: Столбец в БД по которому будет осуществляться поиск записи.

• exclude: Параметры для задания условий исключения из выборки. Может содержать анонимную функцию или массив с полями field и value.

Примеры использования

// Массив полей и значений
$data = [
    'test' => 'admin@admin.ru',
];

// Настройки валидатора
$rules = [
    'test' => [
        'ModelNotExists' => [
            'model'   => \Johncms\Users\User::class,
            'field'   => 'mail',
            'exclude' => static function ($query) {
                return $query->where('name', '!=', 'admin')->where('id', '!=', 1);
            },
        ],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

В примере выше выполняется проверка наличия в таблице users пользователя с полем mail, содержащим admin@admin.ru. При этом из выборки исключаются строки с name = admin и id = 1. Для расширения запроса на выборку используется анонимная функция. Она позволяет дополнять запрос любыми условиями. Валидатор выполнит следующий запрос:

select * from `users` where (`name` != 'admin' and `id` != 1) and `mail` = 'admin@admin.ru' limit 1

Рассмотрим более простой пример, где в параметр exclude передается массив:

// Массив полей и значений
$data = [
    'test' => 'admin@admin.ru',
];

// Настройки валидатора
$rules = [
    'test' => [
        'ModelNotExists' => [
            'model'   => \Johncms\Users\User::class,
            'field'   => 'mail',
            'exclude' => [
                'field' => 'name',
                'value' => 'admin',
            ],
        ],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

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

select * from `users` where `name` != 'admin' and `mail` = 'admin@admin.ru' limit 1

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

// Массив полей и значений
$data = [
    'test' => 'admin@admin.ru',
];

// Настройки валидатора
$rules = [
    'test' => [
        'ModelNotExists' => [
            'model'   => \Johncms\Users\User::class,
            'field'   => 'mail',
        ],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

При таких настройках валидатор просто проверит наличие записи с mail = admin@admin.ru. Если запись будет найдена, то валидатор вернёт ошибку. Если нет, проверка пройдет успешно.

Запрос, который выполнит валидатор при этих настройках будет таким:

select * from `users` where `mail` = 'admin@admin.ru' limit 1

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

Поддерживаемые параметры

• sessionField: Указывается ключ в сессии из которого валидатор будет использовать код. По умолчанию: code

Примеры использования

// Массив полей и значений
$data = [
    'test' => 'captcha_code',
];

// Настройки валидатора
$rules = [
    'test' => [
        'Captcha',
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

В указанном выше примере код код будет использоваться из переменной по умолчанию $_SESSION['code']

// Массив полей и значений
$data = [
    'test' => 'captcha_code',
];

// Настройки валидатора
$rules = [
    'test' => [
        'Captcha' => [
            'sessionField' => 'captcha_code'
        ],
    ],
];

// Валидация
$validator = new \Johncms\Validator\Validator($data, $rules);
if ($validator->isValid()) {
    echo 'OK';
} else {
    d($validator->getErrors());
}

А в этом примере будет использован код из переменной $_SESSION['captcha_code']

Более подробно работу с формами и с капчей рассмотрим в отдельной статье.

Давайте создадим свой первый простой шаблон. Начнем с задачи, которая изначально возникнет практически у всех, кто установит себе JohnCMS: мы будем менять Главную страницу сайта и логотип. Перед тем, как взяться за создание своего шаблона, давайте составим примерный план предполагаемых работ.

Что мы сделаем?

• Создадим свою тему с названием "lesson"

• Поменяем Главную страницу сайта. Вместо имеющегося по умолчанию текста, на ней крупными буквами выведем "Добро пожаловать!"

• Заменим логотип сайта. Вместо JohnCMS будем использовать свою .PNG картинку.

• Изменим цвет боковой панели навигации: вместо белого использовать какой-нибудь темный оттенок, подходящий по дизайну. Соответственно поменяем цвет иконок.

Пошаговая инструкция

1. В папке /themes создаем папку lesson

2. Заходим в админку и далее в системные настройки. Там в списке имеющихся тем мы увидим нашу lesson. Выбираем ее и нажимаем "Сохранить". Теперь для нашего сайта применена тема "lesson" и все, что мы будем в ней делать, сразу же будет видно.

3. Чтобы поменять Главную страницу сайта, мы должны отредактировать ее шаблон, который находится в модуле /modules/homepage. В папке с модулем есть папка /templates а в ней лежит файл index.phtml - это и есть Главная страница, этот файл нам и нужен. Из предупреждения выше мы знаем, что менять шаблон в самом модуле нельзя, поэтому мы должны сначала скопировать файл шаблона в свою тему, и только потом его изменять. Не переместить, а именно скопировать, оригинал файла должен остаться на своем месте

4. Куда? /themes/lesson - это папка с нашей темой, которую мы создали выше. Мы должны скопировать сюда файл index.phtml из модуля homepage. Для шаблонов в папке с нашей темой должна быть подпапка templates. Чтоб не возникало конфликтов (например файл index.phtml может быть у многих модулей), в папке templates создается подпапка с названием пространства имен для шаблонов модуля (обычно совпадает с именем папки модуля) и уже в нее копируется нужный нам файл.

5. В папке с нашей темой /themes/lesson создаем подпапку templates а в ней подпапку с именем модуля ( в нашем случае это homepage) откуда мы копируем шаблон. В итоге должно получиться /themes/lesson/templates/homepage/ сюда и копируем наш index.phtml Теперь, пока у нас в админке включена наша тема "lesson", для Главной страницы используется именно тот файл, который мы только что скопировали в нашу тему. И все изменения в этом файле сразу будут видны на Главной странице нашего сайта.

Шаблоны располагаются в папке themes

Обычно шаблон для JohnCMS имеет следующую структуру:

• themes

• • template_name

  • • assets

    • src

    • templates

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

Что такое шаблон в JohnCMS?

С точки зрения структуры шаблоном является любая папка в папке /themes В этой папке есть тема по умолчанию - default В этой теме находятся все необходимые для работы файлы по умолчанию: шаблоны, стили, картинки, скрипты и т.д. Также, каждый отдельный модуль может иметь свою папку с шаблонами /module_name/templates, или другими файлами общего доступа /assets/modules/module_name.

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

• modules

  • vendor_name

    • module_name

      • config

        • routes.php

      • src

        • Controllers

        • Install

      • locale

      • templates

      • composer.json

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

Давайте подробнее посмотрим на структуру и разберемся что и для чего предназначено.

• modules - это обычная системная папка с модулями.

  • vendor_name - Имя разработчика модуля

    • module_name - это папка с названием модуля (например forum, community и т.п.)

      • config - содержит конфигурационные файлы модуля.

        • routes.php - файл с настройками маршрутов модуля.

      • src - папка с классами модуля (используется для автозагрузки классов и будет иметь пространство имен VendorName\ModuleName)

        • Controllers - папка с контроллерами. Пространство имен VendorName\ModuleName\Controllers

        • Install - папка с установочными файлами. Пространство имен VendorName\ModuleName\Install

      • locale - это папка в которой хранятся файлы локализации модуля. Если модуль мультиязычный, то эта папка обычно есть.

      • templates - в этой папке хранятся шаблоны модуля.

      • composer.json - файл с некоторыми основными параметрами. Подробнее смотрите ниже.

Автоматическая загрузка классов реализуется с помощью файла composer.json.

Пример файла composer.json:

В этом примере стоит обратить внимание на следующие значения:

• name - Название модуля с указанием разработчика vendor_name/module_name

• type - Обязательно должен быть johncms-module

• autoload - В этой секции описываются правила автозагрузки классов вашего модуля. Рекомендуется делать так же как указано в примере. Параметр Johncms\\Auth\\ это пространство имен, а src/ это папка в папке с модулем из которой будут загружаться классы. Начальный сегмент пространства имен обычно содержит в себе имя разработчика (Johncms) и название модуля (Auth). Каждое слово следует начинать с заглавной буквы.

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

Как нам уже известно, модули располагаются в папке modules

Сначала давайте создадим папку с модулем и назовем её contacts путь к папке получится такой: modules/contacts

Пока создадим простой модуль без мультиязычности.

Внутри папки modules/contacts создадим подпапку templates для шаблона нашей страницы. Так же создадим папку Controllers для контроллеров. После выполнения этих действий у вас должна получиться такая структура:

Дополнительные папки нам больше не понадобятся.

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

Контроллеры являются обычными php классами которые наследуют системный класс контроллера. В JohnCMS используется автозагрузка классов модулей. Чтобы она работала, нужно придерживаться некоторых правил:

2. Для работы автозагрузки классов модуль должен быть зарегистрирован в системе. Как это сделать рассмотрим ниже.

Регистрация модуля

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

Создайте в папке config/autoload файл с именем modules.local.php и следующим содержимым

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

В нашем случае пространством имен будет Contacts

Создание контроллера

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

Контроллеры модуля должны наследовать Johncms\Controller\BaseController

Давайте наконец создадим наш контроллер. Создадим файл ContactsController.php со следующим содержимым:

Это минимальный набор кода, который понадобится для работы.

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

Для автоматической базовой настройки шаблонизатора и загрузки файлов локализации нам понадобится добавить свойство $module_name с названием папки модуля (в нашем случае contacts).

Теперь нам нужно дополнить метод index.

Далее давайте установим заголовок страницы в тегах title и h1. Для этого в шаблонизатор нужно добавить 2 переменные с именем title и page_title. Делается это следующим образом:

Далее нам нужно добавить нашу страницу в цепочку навигации.

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

Обратите внимание на последнюю строку. Шаблонизатор так же имеет свое пространство имен для шаблонов. Оно автоматически регистрируется в базовом контроллере и является названием папки с модулем. В нашем случае contacts это название нашего модуля, а index это название файла шаблона из папки templates. Вторым параметром ['data' => $data] передается массив данных, которые будут доступны в шаблоне. Ключи этого массива будут использоваться как названия переменных, а значения в качестве значений. В данном примере в шаблоне у нас будет доступна переменная data и она будет содержать массив с контактными данными.

Полный код файла контроллера

Создание шаблона

Далее давайте создадим наш шаблон. Шаблон будет располагаться в папке templates и т.к. это основная страница контактов, назовем шаблон index.phtml

Добавление маршрута

Наш модуль готов, но пока ещё не доступен в браузере. Давайте это исправим. Чтобы модуль стал доступен, нужно сообщить системе, что у нас есть такой модуль и мы хотим чтобы он был доступен по определенному адресу. Для этого давайте перейдем в папку config и в ней создадим файл routes.local.php если его ещё нет. Если есть, то откроем его и добавим маршрут для нашего модуля.

Теперь наш модуль доступен по адресу ваш.сайт/contacts/

Теперь давайте сообщим модулю online, что у нас появился модуль контактов и нужно в списке пользователей онлайн отображать тех, кто смотрит контакты. Для этого давайте перейдем в папку config и в ней создадим файл places.local.php если его ещё нет.

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

Начиная с JohnCMS 9.0.0 в системе используются современные средства для сборки файлов стилей и скриптов. Вы можете конечно не использовать эти средства, но они существенно облегчают разработку после того как вы разберетесь с ними.

Давайте разберемся как же нам теперь работать с нововведениями... Для работы сборщика нам понадобится Node.js. Вы можете скачать его с официального сайта Скачайте и установите Node.js на ваш компьютере. После установки перезагрузите компьютер. Установите JohnCMS на своем компьютере если ещё не установили.

Давайте разберемся где у нас подключаются стили и js и начнем делать свою тему на основе этого.

Откроем файл themes/default/templates/system/layout/default.phtml Как вы наверное догадались это основной шаблон нашего сайта.

Вверху найдем строчку:

Эта строка у нас подключает css файл из папки themes/default/assets/css/app.css

Внизу строчку:

Эта строчка подключает javascript из папки themes/default/assets/js/app.js

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

Давайте разберемся со сборщиком. Настройка сборщика производится в файле /webpack.mix.js (в корне сайта). Давайте откроем его и посмотрим что там есть. Найдем там 2 строчки которые там нужны:

Что-то знакомое тут, не правда ли? Давайте разберемся, что у нас тут для чего.

Эта строчка говорит сборщику чтобы он взял файл по пути themes/default/src/js/app.js произвел все необходимые операции с ним и положил его в папку themes/default/assets/js. Т.к. во втором параметре мы явно не указали название файла, сборщик соберет файл и сохранит с таким же именем что и исходный файл т.е. app.js. В итоге получится так: themes/default/assets/js/app.js

Посмотрим на вторую строку

В этой строке мы говорим сборщику чтобы он взял файл themes/default/src/scss/app.scss, преобразовал его в пригодный для браузера вид, сжал и положил его в папку themes/default/assets/css. Т.к. название файла явно не указали, сборщик назовет файл так же как и исходный, но расширение укажет css. т.е. app.css. В итоге получится так: themes/default/assets/css/app.css

Теперь мы разобрались как у нас попадают файлы app.js и app.css в нужные папки.

Давайте теперь создадим свою тему и настроим сборщик так, чтобы он собирал ещё и стили и скрипты в нашей теме. Создаем в папке themes подпапку с нашей темой my_theme Из папки с темой default давайте скопируем 2 папки. src и assets На этом наша тема готова к сборке. Теперь давайте расскажем о ней сборщику и соберем наши стили и скрипты.

Открываем файл /webpack.mix.js Вставим после строки

следующие 2 строки:

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

На этом сборщик настроен и уже будет работать.

Давайте откроем командную строку, перейдем в папку с установленным johncms для этого наберите cd и путь к папке в которой установлен johncms. После этого давайте установим зависимости и запустим сборщик. Выполните команду npm install Эта команда установит bootstrap и прочие библиотеки, необходимые для работы.

После этого выполните команду npm run watch

Эта команда соберет app.js и app.css и будет следить за изменением исходных файлов и пересобирать app.js и app.css когда вы изменяете исходные файлы. В результате её выполнения вы должны увидеть следующее:

Давайте теперь разбираться в структуре css и js. Откроем файл: themes/my_theme/src/js/app.js Этот файл является основным и в нем подключаются все дополнительные файлы. Все дополнительные файлы лежат в той же папке что и основной файл. Вы можете открывать их, редактировать или смотреть что в них находится.

Откроем файл: themes/my_theme/src/scss/app.scss так же как и app.js этот файл является основным файлом в котором подключаются все дочерние.

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

Эта строка подключает файл sidebar.scss из той же папки что и app.scss Давайте откроем файл sidebar.scss В этом файле мы видим практически привычный CSS код. Но он поддерживает вложенность селекторов и прочие возможности. Вы можете подробнее прочитать про SCSS (SASS) на просторах интернета или спросить у нас на форуме.

И так, давайте поменяем всё таки цвет нашего меню. Цвет меню задан прямо во второй строке:

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

Обратите внимание, что команда npm run watch выполняет сборку, но не выполняет сжатие CSS и JS файлов для ускорения работы. Перед тем, как вы захотите выгрузить изменения на сайт, выполните команду npm run prod она соберет файлы и выполнить минификацию. После этого размер файлов будет меньше.

Примечание: После создания темы, не забудьте зайти в настройки и выбрать новую тему :)

Для чего нужен роутер в JohnCMS?

Как и в других CMS и фреймворках роутер в JohnCMS обрабатывает запрошенный URL адрес и определяет какой модуль запустить для обработки этого запроса. В свою очередь модуль может получить от роутера различные параметры в зависимости от настроек маршрута и использовать для реализации своего функционала.

Перейдем к практической части.

Где хранятся настройки маршрутизации?

Все описания маршрутов хранятся в модулях по следующему пути: config/routes.php

Пример файла routes.php

Давайте теперь рассмотрим детально как работать с роутером и как использовать его в своих модулях?

Возьмём простой пример из кода выше. Маршрут у нас в нем задается такой строкой:

Эта строка говорит роутеру следующее: Если запрос пришел методом GET и он поступил на страницу site.ru/contacts/, то необходимо вызвать метод index в контроллере Johncms\Contacts\Controllers\ContactseController Таким образом, когда пользователь переходит по адресу site.ru/contacts/ он видит те данные, которые вернул метод index.

Откроем файл /config/routes.local.php

Изменим нашу строку маршрута следующим образом:

Мы добавили в неё дополнительный параметр {action?} Что это значит? Вопросительный знак сообщает роутеру, что этот параметр не обязателен (он может быть, а может отсутствовать). В фигурных скобках задается название параметра, чтобы модуль смог с ним работать. По умолчанию выбираться будет та часть адреса, которая расположена между /contacts/ и следующим слэшем.

Чтобы было понятнее, давайте разберем на примерах. 1. site.ru/contacts/ - В таком варианте у нас параметр action будет игнорироваться т.к. роутер считает его необязательным и откроет нашу страницу контактов. 2. site.ru/contacts/moscow - Такой вариант откроет нашу страницу контактов и в модуле будет доступен параметр action. В этом параметре будет содержаться слово "moscow". 3. site.ru/contacts/new_york - Тоже самое что и в варианте 3, только в параметре action будет "new_york" 4. site.ru/contacts/new_york/test1/ - Выдаст ошибку 404 т.к. роутер видит, что маршрут не подходит нам (содержит больше данных чем нужно для нашего маршрута).

Получение параметров маршрута в контроллере

Давайте теперь разберемся как в модуле нам получить параметры, которые мы указываем в роутере. Откроем файл контроллера Controllers/ContactsController.php В методе index вставим следующий код

Перейдем по адресу: site.ru/contacts/moscow/

В браузере у вас отобразится следующий текст:

Как мы видим, параметр, который мы назвали в настройках маршрута action, появился у нас в массиве и содержит слово moscow.

В модуле мы можем обратиться к этому параметру и в зависимости от его содержимого управлять логикой работы модуля. Получить этот параметр можно, как вы наверное уже догадались, следующим образом: $route['action']

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

В нашем случае в переменной $action будет содержаться слово moscow.

Прочие примеры использования

Указание регулярного выражения для сопоставления маршрута

В примере выше регулярное выражение ограничивает тип параметра page до числа. Если после строки /contacts/ будут буквы - маршрут не будет сопоставлен и отобразится 404 страница.

Установка метода запроса

Роутер позволяет задавать методы для которых будет доступен маршрут.

Шаблоны популярных выражений

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

Группы маршрутов

Поддерживается возможность объединения маршрутов в группу

В примере описанном выше будут обрабатываться следующие ссылки: /admin/login/ /admin/login/authorize/

Имена маршрутов так же будут иметь префикс admin. (admin.login, admin.authorize)

Генерация URL по имени маршрута

При объявлении маршрута можно указывать его имя с помощью метода ->setName('routeName'). Далее это имя можно использовать для генерации ссылок:

Можно так же генерировать маршруты с параметрами:

Установка приоритета

Бывают случаи когда один адрес может попадать под одно и то же регулярное выражение. Например если у вас есть маршрут с динамическим параметром, но для конкретной страницы которая попадает под этот маршрут вам нужно сделать отдельный контроллер.

В этом примере URL /path/test-action попадает под шаблон первого маршрута, но т.к. мы указали приоритет второго маршрута выше чем первого, второй маршрут отработает раньше.

Добавление middleware

Middleware будут выполняться в следующем порядке:

1. Глобальные для всех маршрутов (из конфигов)

2. Для группы

3. Для конкретных маршрутов

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

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

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

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

В центральной части страницы вы увидите её подтвержденный перевод если он есть и список автоматически сгенерированных переводов. Введите перевод или выберите готовый и нажмите Сохранить (Save).

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

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

PDO

Этот вариант многим известен и применяется ещё с JohnCMS 7.0. Давайте рассмотрим особенности использования этого варианта. Чтобы получить объект PDO нам достаточно написать следующий код:

Далее используя объект $db вы можете выполнять запросы к базе данных. Рассмотрим пример, который получает записи из таблицы users:

Этот пример выведет список имен пользователей, которые есть в таблице users.

Конструктор запросов (Query Builder)

В JohnCMS для работы с БД используется библиотека которая и предоставляет конструктор запросов и ORM. Рассмотрим несколько основных примеров чтобы понять особенности работы с библиотекой в JohnCMS.

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

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

Этот запрос так же как и в предыдущем варианте выведет список имен пользователей, которые есть в таблице users. Метод get возвращает объект Illuminate\Support\Collection c результатами, в котором каждый результат — это экземпляр PHP-класса StdClass. Вы можете получить значение каждого столбца, обращаясь к столбцу как к свойству объекта. Давайте рассмотрим вариант получения одной строки из таблицы.

Этот запрос вернет пользователя, у которого поле name равно admin.

Рассмотрим вариант вывода записей из таблицы с разбивкой на страницы по 5 элементов:

При вызове метода paginate будет автоматически установлены ограничения для запроса и построен запрос количества элементов в таблице по указанному вами запросу. Т.е. при таком вызове вам не нужно заботиться об указании limit для запроса и не нужно строить запрос на количество записей, конструктор запросов сделает это за вас. При вызове метода render из нашего объекта, будет отрисована постраничная навигация. URL адреса будут построены исходя из текущей страницы. Вам так же не нужно заботиться об их формировании. Шаблон вывода постраничной навигации расположен тут: themes/default/templates/system/app/model_paginator.phtml

Выборка только необходимых столбцов

Иногда вам может понадобиться выбрать только определенные столбцы из таблицы в базе данных. Сделать это можно так:

Для выборки конкретных столбцов используется метод select(). Он принимает названия столбцов в виде массива или просто списком аргументов. Например: select('name', 'id')

Сортировка результата выборки

Часто есть необходимость отсортировать результат выборки по какому-либо столбцу.

В этом примере результат будет отсортирован по id и name. Метод orderBy вторым аргументом принимает направление сортировки asc или desc. По умолчанию asc. Метод orderByDesc это то же самое, что и orderBy('id', 'desc') Как видно из примера, сортировать можно по нескольким колонкам. Указанный выше пример выполнит следующий запрос к базе данных:

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

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

Переходим по ссылке

Вам необходимо авторизоваться на сайте. Если у вас уже есть учетная запись на crowdin.com или вы зарегистрированы в Facebook, Google, Twitter, Github или Gitlab, то можете нажать на кнопку Log in. Перед вами появится окно авторизации в котором вы можете ввести логин и пароль от учетной записи или войти через описанные выше сервисы. Если учетной записи нет, то нажимаете на Sign up и регистрируетесь.

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

После выбора языка перед вами появится эта страница:

На этой странице отображен список переводов для модулей системы и процент фраз, которые уже переведены.

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

В левой части отображается список фраз для перевода. В центре отображается сам перевод и информация о том, в каких файлах содержится фраза (context). Так же вы можете посмотреть как эта фраза переведена на другие языки, для этого разверните блок OTHER LANGUAGES. Так же есть уже автоматически переведенные варианты (TM and MT Suggestions), которые вы можете выбрать если там есть подходящий вариант. Если подходящего варианта в автоматических переводах нет, то нужно вписать перевод вручную в поле ввода и нажать Save (сохранить). После сохранения автоматически откроется следующая фраза для перевода в текущем модуле.

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

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

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

JohnCMS как и многие другие системы для работы использует базу данных. Когда вы устанавливаете систему, создается файл config/autoload/database.local.php в этом файле хранятся настройки подключения к базе данных.

На данный момент по умолчанию он выглядит так:

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

В параметре db_port указывается порт, который используется для подключения к БД. В параметре db_driver указывается драйвер для работы с базой данных.

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

В JohnCMS по умолчанию предустановлены несколько языков. В этом разделе мы разберемся как с ними работать и как переводить ваши модули на различные языки, которые вам нужны.

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

Как сделать модуль мультиязычным?

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

Простой перевод фраз

Множественное/единственное число

В примере выше первым аргументом передается фраза в единственном числе. Вторым аргументом передается фраза во множественном числе. Третьим аргументом передается само число из-за которого будет приниматься решение какую фразу выбрать (если будет передано число 1, то выведется фраза One apple, если будет передано число 5, то будет выведено 5 apples). Четвертым и последующими аргументами передаются данные, которые будут заменены в строке для перевода. Например в указанной фразе %s будет заменено на число 5.

Перевод фраз в зависимости от контекста

Часто есть необходимость в одном файле написать фразы, которые могут писаться на английском языке одинаково, а на другом языке по-разному в зависимости от контекста. Чтобы разделить такие фразы вы можете использовать функцию p__(). Первым аргументом передается название контекста, а вторым передается фраза, которая будет переводиться.

Множественное/единственное число в зависимости от контекста

Перевод из определенного домена

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

Перевод из определенного домена и контекста

Множественное/единственное число из определенного домена

Множественное/единственное число из определенного домена и контекста

Структура

Для хранения переводов в модулях предусмотрена папка locale. Все переводы по умолчанию разбиваются по группам (так называемым доменам). Это позволяет избегать пересечения переводов из разных частей системы. По умолчанию все фразы модуля сгруппированы в группу с названием модуля без имени разработчика. (например для модуля johncms/news группа (домен) будет называться news).

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

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

В примере выше в метод addTranslationDomain подается название домена и путь к папке в которой хранятся переводы.

Создание переводов

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

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

Для работы с gettext нам нужен базовый pot файл который содержит исходные фразы-ключи. Чтобы его создать давайте в корне проекта создадим файл translate.xml со следующим содержимым:

В этом файле в теге domain > name указывается название домена (обычно это название модуля). В target - папка с переводами, а sourceDir - папка с исходными кодами вашего модуля (обычно это папка с самим модулем).

После создания этого файла откройте консоль и выполните команду

Все переведенные файлы сохраняйте в папку из которой вы открыли .pot файл.

Всё что дельше от вас потребуется, это сконвертировать перевод в php массив. Для этого выполните следующую команду:

После выполнения этой команды появится файл с кодом языка и расширением .lng.php На этом перевод завершен и если вы откроете модуль в браузере, вы увидите перевод фраз, который выполнили.