Создание модулей - правка API через файлы модулей

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

Принцип работы

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

Основные принципы модульности

  1. Независимость кода от общей логики

  2. Перехват глобальных переменных

  3. Перехват и создание нового ЧПУ

  4. Легкая установка и удаление

  5. Подключение персонального меню управления

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

  7. Обновление модулей

Образно говоря, создав модуль, можно перехватывать общие глобальные переменные для главных шаблонов index.tpl и shop.tpl, создавать новые виртуальные категории или менять существующие (/page/, /catalog/ и т.д.), и внедрять интерфейсы управления модулем в общий стиль административной панели через простой стандарт подключения модуля, описанный на языке XML.

Описание файловой системы модуля

Все модули находятся в папке /phpshop/modules/имя_модуля.

  1. templates - шаблоны

  2. core - файлы для создания ЧПУ( site.ru/catalog/ и т.д.)

  3. install - установочные файлы

    1. install/module.sql - SQL файл для установки таблиц

    2. install/module.xml - описание модуля и меню навигации управления для администрирования

  4. inc - файлы основной логики

    1. inc/config.ini - файл конфигурации

  5. class - файлы с классами основной логики

  6. admpanel - файлы административных интерфейсов

  7. updates - доступные обновления

    1. default - обновления без привязки к версии модуля если не указана версия при установке модуля

    2. 1.0 - обновления для версии модуля 1.0

    3. 1.1 - обновления для версии модуля 1.1

Подключение ЧПУ

Для создания нового виртуального раздела ( site.ru/catalog/ и т.д.) требуется внести в конфигуратор модуля config.ini запись о новом разделе формата уникальное имя нового раздела = "путь до файла логики", пример:

[core]
catalog=".//phpshop/modules/catalog/core/catalog.php";
......

Если уникальное имя нового раздела совпадает с уже существующим разделом, то главным считается файл модуля, а основная логика из папки /phpshop/core/ не учитывается. Данный способ позволяет полностью заменять основную логику платформы. Для облегчения и сокращения кода можно создавать core-файлы модуля, поддерживаемое наследие от основной логики /phpshop/core/, внося только точечные изменения в файл, не затрагивая другие стороны работы раздела.+

Изменить и дописать логику уже существующего раздела можно через Хуки.

Подключение таблиц БД

Если модуль использует таблицы БД, то требуется внести в конфигуратор модуля запись о таблицах формата уникальное имя сокращенного названия = "имя таблицы", пример:

[base]
catalog_load="phpshop_modules_catalog_loads";
catalog_system="phpshop_modules_catalog_system";

При установки модуля таблицы модулей будет созданы из образа БД module.sql и удалены при удалении модуля из списка модулей. Для доступа к именам БД можно воспользоваться классом PHPShopModules:

$PHPShopModules = new PHPShopModules();
$PHPShopModules->getParam("base.catalog.catalog_load");

или

$GLOBALS['SysValue']['base']['catalog']['catalog_system'];

Автозагрузка

Для включения логики в автозагрузку требуется внести в конфигуратор модуля запись папка модуля = "путь до файла загрузки", пример:

[autoload]
catalog=".//phpshop/modules/catalog/inc/catalog.inc.php";

Указанный файл /phpshop/modules/catalog/inc/catalog.inc.php должен существовать. Т.к. блок активной логики модулей находится ниже основного блока, то этим приемом можно перехватывать и переписывать глобальные переменные.

Шаблоны

Если модуль использует шаблоны дизайна, то требуется внести в конфигуратор модуля запись о шаблонах формата уникальное сокращенное имя шаблона = "путь до файла шаблона", пример:

[templates]
catalog_menu_forma=".//phpshop/modules/catalog/templates/catalog_menu_forma.tpl";
catalog_page_forma=".//phpshop/modules/catalog/templates/catalog_page_forma.tpl";
catalog_page_list=".//phpshop/modules/catalog/templates/catalog_page_list.tpl";

Для доступа к шаблонам можно воспользоваться классом PHPShopModules:

$PHPShopModules = new PHPShopModules();
$PHPShopModules->getParam("templates.catalog_page_list");

или

$GLOBALS['SysValue']['templates']['catalog']['catalog_page_list'];

Конфигурация установки

Конфигурация установки модуля описана в файле install/module.xml .

  1. adminmenu - меню в административной панели. При такой конфигурации меню будет доступна из раздела "Модули" -> "Калькулятор Почты<"

  2. faqlink - ссылка на инструкцию

  3. capability - флаг рабоыт модуля в новой версии PHPShop 5

  4. version - версия модуля

  5. category - код категории модуля для навигации в списке модулей

Административные интерфейсы

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

[admpanel]
adm_catalogID="seourl/admpanel/adm_catalogID.php";
adm_catalog_new="seourl/admpanel/adm_catalog_new.php";

Интерфейс настройки модуля

Если модуль содержит опции настройки или параметры регистрации то обязательно наличие интерфейса, записываемый в /phpshop/modules/имя модуля/admpanel/adm_module.php. Для этих целей используется административный интерфейс модуля. Для активации настройки модуля в общем меню и ссылки на дополнительные опции служит файл настроек module.xml.

Дополнения административных интерфейсов (Hook)

Для добавления новых полей служит опция field конфигурации модуля. Файл обработчика должен находится в папке /phpshop/modules/имя модуля/admpanel и иметь тоже название, что и файл для перехвата, пример файла seourl/admpanel/adm_catalogID.php:

// Добавляем значения в функцию actionStart
function addTab(){
global $PHPShopGUI;
return $PHPShopGUI->setField("SEO ссылка:",$PHPShopGUI->setInput("text","seoname_new","catalog","left",300),"none");
}
$addHandler=array(
'actionStart'=>'addTab',
'actionDelete'=>false,
'actionUpdate'=>false
);

Данный пример рисует новое поле SEO в карточке генерации каталога. Массив addHandler описывает в какие функции исходного файла будет внедрен код модуля. В нашем примере в функцию actionStart добавляется логика вывода новой закладки SEO.

Перехват административных интерфейсов (Hook)

Для перехвата логики (обновление, удаление) используется параметр actionUpdate и actionDelete массива addHandler. Для примера перехватим выполнение функции обновления карточки каталога из файла adm_catalogID.php

// Добавляем значения в функцию actionUpdate
function writeContent(){
$_POST['content_new'] = $_POST['name_new'].' Дефолтный контент для описания каталога';
}
$addHandler=array(
'actionStart'=>false,
'actionDelete'=>false,
'actionUpdate'=>'writeContent'
);

Перехват внешних функций (Hook)

Поддерживает внедрение хуков в основную логику внешней части (пользовательская часть сайта) API для перехвата с последующими изменениями результата выполнения методов классов PHPShopCore,PHPShopElements и всех наследуемых от них классов.

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

$this->setHook(__CLASS__,__FUNCTION__,$row,'РОУТЕР');

В новую функцию передается ссылка на объект (родительский класс) и переменная $row - в основном содержащая выборку из БД основной функции. Данная запись позволяет использовать методы исходного класса и массив данных из БД (повторная выборка не требуется). Роутер позволяет координировать место активации хука.

Для использования хука требуется внести в конфигуратор модуля config.ini запись о перехвате метода в классе имя класса = "путь до файла логики", пример:

[hook]
phpshoppage=".//phpshop/modules/users/core/page.core.php";

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

function index_security_hook($obj,$row) {
if(!empty($row['user_security']) and empty($_SESSION['userName'])) {
$obj->set('pageContent',ParseTemplateReturn($GLOBALS['SysValue']['templates']['users']['users_forma'],true));
$obj->set('pageTitle','Только для авторизованных пользователей');
}
}
$addHandler=array(
'index'=>'index_security_hook'
);

Формат описания $addHandler следующий: имя функции для перехвата = "новая функция в этом файле". Результатом выполнения этого хука будет перехват результата выполнения $PHPShopPage->index();

Обновление

Модули поддерживают возможность обновления своей БД. При установке версия модуля пишется в таблицу "phpshop_modules_имя модуля_system" в поле "version" (1.0, 1.1 и т.д.). Версия файлов модуля указывается в install/module.xml тег version. Если версия файлов отличается от версии базы данных (БД), то в закладки информации по модулю будет соответствующая запись о расхождении версий БД с кнопкой "Обновить".

Отладка

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

Адаптация модулей для PHPShop 5

PHPShop 5 имеет немного отличный формат административных интерфейсов по сравнению с предыдущими версиями. Новая панель открывает формы редактирования в общем оформлении, а не в отдельных окнах (как было в предыдущих версиях). Поэтому для миграции модулей во всех административных файлах (пример: returncall/admpanel/adm_module.php, returncall/admpanel/adm_returncallID), которые открывались в отдельном окне нужно убрать несколько строк (подключение к БД и подключение библиотек, так как они уже подключены в общем admin.php).

Сравнение кода модулей

Старая версия записи

$_classPath="../../../";
include($_classPath."class/obj.class.php");
PHPShopObj::loadClass("base");
PHPShopObj::loadClass("system");
PHPShopObj::loadClass("security");
PHPShopObj::loadClass("orm");
$PHPShopBase = new PHPShopBase($_classPath."inc/config.ini");
include($_classPath."admpanel/enter_to_admin.php");
// Настройки модуля
PHPShopObj::loadClass("modules");
$PHPShopModules = new PHPShopModules($_classPath."modules/");
// Редактор
PHPShopObj::loadClass("admgui");
$PHPShopGUI = new PHPShopGUI();
// SQL
$PHPShopOrm = new PHPShopOrm($PHPShopModules->getParam("base.returncall.returncall_system"));

Новая версия записи

// SQL
$PHPShopOrm = new PHPShopOrm($PHPShopModules->getParam("base.returncall.returncall_system"));

Вывод модуля в меню

Для предотвращения возможных ошибок при использование самодельных модулей или модулей, удаленных в новой версии PHPShop 5 (stat, iconcat, tester и др.) введена настройка capability в файл /install/module.xml. При отсутствии тега capability модуль не появится в общем меню доступных модулей после включения. Возможность включить/выключить модуль при этом остается для возможности отключения устарелых модулей из панели управления.

Изменились ссылки дополнительных подменю модулей с ?plugin=returncall на dir.returncall. Тег podmenu_icon больше не используется.+

Работа с БД

Для поддержки ядра самого последнего PHP 7 пришлось отказаться от устаревшей функции соединения с БД MySQL mysql_connect() и заменить ее mysqli_connect. При наличие в модуле нативных функций работы с БД MySQL с префиксом mysql_ необходимо заменить их на одноименные функции с префиксом mysqli_. В качестве ссылки на соединение с БД используется переменная $GLOBALS['link_db'] или $PHPShopBase->link_db или $PHPShopOrm->link_db;

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