Как написать OCMOD-модификатор чтобы он даже работал и ничего не сломать

Сегодня мы разберем такую штуку как OCMOD-модификаторы, странно, но более-менее нормального мануала в сети нет, попробуем исправить этот недостаток так чтобы даже школьник понял как оно работает.

Какие-то неочевидные баги, особенности и приколы мы не будем рассматривать, оставим это удовольствие тем кто решит все-таки пойти дальше и писать свои модули  

Итак, OCMOD-модификатор это простой XML-файл, который изменяет PHP-файлы и/или tpl/twig- файлы шаблонов.

Вообще модификатор - это zip-архив с расширением ocmod.zip

в нем могут быть

папка upload - в которой файлы для загрузки на сервер

файл install.xml - сам XML-модификатор который изменяет файлы

файл install.php - php-файл который выполняется во время установки модификатора

иногда install.sql - то же самое, только для запросов в бд

Это очень небезопасная штука и 90% вирусни на опенкарте - это следствие того что украли админку и загрузили опасные файлы прямо через установщик расширений, я бы отключал вообще этот функционал, а для модулей существуют методы install и uninstall

Но мы будем рассматривать только модификатор, который меняет код в файлах и будем называть его OCMOD-модификатором

Как оно работает

Есть 2 варианта применить модификатор, первый - положить в папочку system файлик с расширением .ocmod.xml, второй - загрузить файл через установщик дополнений.

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

a) есть ограничение на размер файла (правится размером поля в бд, но можно все провтыкать);

б) иногда их блокируют всякие modsecurity;

в) просто тупо неудобно в браузере

Также нужно учитывать что порядок применения модификаторов таков - сначала применяются файлы из папки system по алфавиту, потом файлы из базы по названию или дате добавления

То есть что делать мы уже знаем, чтобы сделать модификатор нам надо сделать xml-файлик и положить его в папку system

Базовая структура OCMOD-файла такая

<?xml version="1.0" encoding="utf-8"?>
<modification>
<name>Name Of Mega Modification - название нашего супер модуля</name>
<code>name_of_mega_modification - внутренний код модификатора</code>
<version>1.0 2.3.x-3.0.x - можно написать версию файла, для каких версий подходит, ну так, чтоб понятно было</version>
<author>spectre - ваш супер ник</author>
<link>https://freelancer.od.ua/ - ваш суперсайт</link>

Здесь будет основное колдунство 
  
</modification>

Как и в любом XML-файле все теги должны быть открыты и закрыты после содержания

Ну, раз мы уже начали делать модификатор, давайте придумаем что он будет делать и по дороге обратим внимание на то как можно делать в OCMOD а как не надо.

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

Сделаем радиокнопочку, которая будет включать и выключать наше творение, а также надпись на какую собственно будет заменяться кнопка "купить", обычную, не мультиязычную, когда научитесь писать модификаторы-  научитесь брать готовые части кода, благо в опенкарте уже есть все примеры)

 Делать будем на последней версии OcStore 2.3.0.2.4

Структура операции в OCMOD файле очень простая

<file path="Путь к файлу"> 
	<operation error="действие при ошибке">
		<search><![CDATA[что ищем]]></search>
		<add position="операция"><![CDATA[ 
			что вставляем или меняем
		]]></add>
	</operation>
</file>

Путь к файлу, который мы будем модифицировать

Можно написать несколько путей через |

<file path="catalog/controller/common/home.php|catalog/controller/common/column_left.php"> 

В пути можно использовать звездочки и скобочки

* - это любой символ в пути

{} - это набор файлов, подробнее опишу дальше

Сейчас мы делаем админку для нашего модификатора и нам понадобятся файлы

admin/controller/setting/setting.php

admin/view/template/setting/setting.tpl

т.е. операция примет вид

<file path="admin/view/template/setting/setting.tpl"> 
	<operation error="skip">
		<search><![CDATA[<label class="col-sm-2 control-label" for="input-admin-limit"><span data-toggle="tooltip" title="<?php echo $help_limit_admin; ?>"><?php echo $entry_limit_admin; ?></span></label>]]></search>
		<add position="before"><![CDATA[ 
			
		]]></add>
	</operation>
</file>

действие при ошибке - необязательно, но я предпочитаю писать skip - просто пройти дальше мимо

можно писать abort (не надо, это оборвет исполнение всей цепочки) или log (писать в лог, но вроде и так все пишется)

Нам нужна радиокнопка которая вкл-выкл действие и сама надпись для этой кнопки

Откроем файл шаблона настроек магазина admin/view/template/setting/setting.tpl и найдем похожий кусочек с радиокнопкой на вкладке "Опции", а заодно и текстовое поле

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

Окей, найдем в tpl-файле этот кусочек кода (для простоты перед ним и будем вставлять наши настройки)

Теперь подумаем куда нам прицепиться.

Самое главное для OCMOD файла - найти УНИКАЛЬНЫЙ ЭЛЕМЕНТ к которому мы будем привязываться, не к <?php echo $text_yes; ?>, не к <div class="form-group required"> а к чему-то что с малой вероятностью будет изменено коллегами-конкурентами-вашими программистами

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

На этом примере мы можем прицепиться к 

<legend><?php echo $text_product; ?></legend>

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

Смотрим, нам нужно вклиниться вот сюда

Закрывающий див не подходит, form-group тоже, мы не планируем считать какой это обязательный блок во всем файле

я вижу уникальную конструкцию это название блока "кол-во элементов в админке" - туда и пойдем

Берем всю строчку и указываем что ее нужно искать (надо вставлять без переносов и пробелов в начале и в конце

<search><![CDATA[<label class="col-sm-2 control-label" for="input-admin-limit"><span data-toggle="tooltip" title="<?php echo $help_limit_admin; ?>"><?php echo $entry_limit_admin; ?></span></label>]]></search>

search понимает параметр index , то есть если написать <search index="3"><![CDATA[</label>]]></search> то наш код будет исполняться около 4(!) вхождения </label> на странице - первый элемент это index="0". Старайтесь не использовать это без особой необходимости, кто-то вставит раньше похожий кусочек и все сломается, ваша задача максимально оградить себя от внешних влияний. 

Без параметра index - операция применится ко всем вхождениям искомой строки в файле

Можно искать по части строки, но старайтесь по целой

Еще search понимает атрибут trim, но обычно это не применяется на практике

Теперь будем наконец-то вставлять код.

Берем просто копипастим радиокнопку вместе с текстовым полем и переименовываем переменные в 1 - то что нам надо, 2 - чтобы тот кто откроет после вас понял что имеется ввиду

Получается что-то такое

           <div class="form-group">
             <label class="col-sm-2 control-label"><span data-toggle="tooltip" title="<?php echo $help_replace_cart_button; ?>"><?php echo $entry_replace_cart_button; ?></span></label>
             <div class="col-sm-10">
               <label class="radio-inline">
                 <?php if ($config_replace_cart_button) { ?>
                 <input type="radio" name="config_replace_cart_button" value="1" checked="checked" />
                 <?php echo $text_yes; ?>
                 <?php } else { ?>
                 <input type="radio" name="config_replace_cart_button" value="1" />
                 <?php echo $text_yes; ?>
                 <?php } ?>
               </label>
               <label class="radio-inline">
                 <?php if (!$config_replace_cart_button) { ?>
                 <input type="radio" name="config_replace_cart_button" value="0" checked="checked" />
                 <?php echo $text_no; ?>
                 <?php } else { ?>
                 <input type="radio" name="config_replace_cart_button" value="0" />
                 <?php echo $text_no; ?>
                 <?php } ?>
               </label>
             </div>
           </div>
           <div class="form-group">
             <label class="col-sm-2 control-label" for="input-replace-cart-button-text"><span data-toggle="tooltip" title="<?php echo $help_replace_cart_button_text; ?>"><?php echo $entry_replace_cart_button_text; ?></span></label>
             <div class="col-sm-10">
               <input type="text" name="config_replace_cart_button_text" value="<?php echo $config_replace_cart_button_text; ?>" placeholder="<?php echo $entry_replace_cart_button_text; ?>" id="input-replace-cart-button-text" class="form-control" />
             </div>
           </div>			

Теперь нам нужно вставить это перед блоком, но там div с классом form-group

используем before offset="1" - это значит что операция начнет применяться на 1 строку выше той которую мы ищем

точно так же работает after - это вставка после искомой строки

replace - заменяет искомую строку на то что мы напишем

несколько строк одновременно в одной операции поиска искать нельзя!

У нас получится такая операция и с этим файлом мы закончили

	<operation error="skip">
		<search><![CDATA[<label class="col-sm-2 control-label" for="input-admin-limit"><span data-toggle="tooltip" title="<?php echo $help_limit_admin; ?>"><?php echo $entry_limit_admin; ?></span></label>]]></search>
		<add position="before" offset="1"><![CDATA[ 
           <div class="form-group">
             <label class="col-sm-2 control-label"><span data-toggle="tooltip" title="<?php echo $help_replace_cart_button; ?>"><?php echo $entry_replace_cart_button; ?></span></label>
             <div class="col-sm-10">
               <label class="radio-inline">
                 <?php if ($config_replace_cart_button) { ?>
                 <input type="radio" name="config_replace_cart_button" value="1" checked="checked" />
                 <?php echo $text_yes; ?>
                 <?php } else { ?>
                 <input type="radio" name="config_replace_cart_button" value="1" />
                 <?php echo $text_yes; ?>
                 <?php } ?>
               </label>
               <label class="radio-inline">
                 <?php if (!$config_replace_cart_button) { ?>
                 <input type="radio" name="config_replace_cart_button" value="0" checked="checked" />
                 <?php echo $text_no; ?>
                 <?php } else { ?>
                 <input type="radio" name="config_replace_cart_button" value="0" />
                 <?php echo $text_no; ?>
                 <?php } ?>
               </label>
             </div>
           </div>
           <div class="form-group">
             <label class="col-sm-2 control-label" for="input-replace-cart-button-text"><span data-toggle="tooltip" title="<?php echo $help_replace_cart_button_text; ?>"><?php echo $entry_replace_cart_button_text; ?></span></label>
             <div class="col-sm-10">
               <input type="text" name="config_replace_cart_button_text" value="<?php echo $config_replace_cart_button_text; ?>" placeholder="<?php echo $entry_replace_cart_button_text; ?>" id="input-replace-cart-button-text" class="form-control" />
             </div>
           </div>			
		]]></add>
	</operation>

теперь нужно вдохнуть жизнь в переменные

У нас здесь 2 переменные настроек

это $config_replace_cart_button и $config_replace_cart_button_text а также языковые переменные

открываем 

admin/controller/setting/setting.php

и ищем там 2 места

где добавляются языковые переменные 

и непосредственно сохраняются настройки, ищем config_product_count

у нас будет 2 операции (можно в одной, но лучше текстовые переменные туда где текстовые, а настройки к настройкам, чтобы выглядело "как родное"

Точно так же копипастим код, переименовываем переменные и получаем что-то такое

<file path="admin/controller/setting/setting.php"> 
	<operation error="skip">
		<search><![CDATA[$data['entry_status'] = $this->language->get('entry_status');]]></search>
		<add position="after"><![CDATA[ 
           $data['entry_replace_cart_button'] = $this->language->get('entry_replace_cart_button');
           $data['help_replace_cart_button'] = $this->language->get('help_replace_cart_button');
           $data['entry_replace_cart_button_text'] = $this->language->get('entry_replace_cart_button_text');
           $data['help_replace_cart_button_text'] = $this->language->get('help_replace_cart_button_text');
		]]></add>
	</operation>
	<operation error="skip">
		<search><![CDATA[if (isset($this->request->post['config_product_count'])) {]]></search>
		<add position="before"><![CDATA[ 
		
		if (isset($this->request->post['config_replace_cart_button'])) {
			$data['config_replace_cart_button'] = $this->request->post['config_replace_cart_button'];
		} else {
			$data['config_replace_cart_button'] = $this->config->get('config_replace_cart_button');
		}
		if (isset($this->request->post['config_replace_cart_button_text'])) {
			$data['config_replace_cart_button_text'] = $this->request->post['config_replace_cart_button_text'];
		} else {
			$data['config_replace_cart_button_text'] = $this->config->get('config_replace_cart_button_text');
		}

		]]></add>
	</operation>
</file>

Здесь offset нам не нужен, просто вставляем до и после

Всегда проверяйте что то, к чему привязываемся - уникально!

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

Язык админки у нас может быть разный, но мы сделаем так чтобы везде появились эти языковые переменные и попробуем символ * в пути

<file path="admin/language/*/setting/setting.php"> 

Это значит что наш модификатор пробежится по всем папкам в admin/language и поищет в каждой файл setting/setting.php

Можно написать так <file path="admin/language/*/*/set*.php"> или так <file path="admin/*/*/*/setting.php">

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

<file path="admin/language/{ru-ru,en-gb}/setting/setting.php"> 

это явное указание нескольких папок-файлов в пути

в них обоих есть // Text поэтому не будем мудрствовать лукаво

<file path="admin/language/{ru-ru,en-gb}/setting/setting.php"> 
	<operation error="skip">
		<search><![CDATA[// Text]]></search>
		<add position="after"><![CDATA[ 
		$_['entry_replace_cart_button']        = 'Заменять кнопку "купить" при нулевом остатке';
		$_['help_replace_cart_button']         = 'Если включить - будет работать замена';
		$_['entry_replace_cart_button_text']   = 'Текст на кнопке купить при количестве 0';
		$_['help_replace_cart_button_text']    = 'Будет отображаться на кнопке при нулевом количестве';
		]]></add>
	</operation>
</file>

И, о чудо, админку для модуля мы написали и она даже работает!

Теперь будем делать самое главное - чтобы это все работало

Начнем с товара, это контроллер product/product и шаблон по такому же пути

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

Получаем

<file path="catalog/controller/product/product.php"> 
	<operation error="skip">
		<search><![CDATA[$data['points'] = $product_info['points'];]]></search>
		<add position="after"><![CDATA[ 
		$data['quantity'] = $product_info['quantity'];
		$data['replace_cart_button_status'] = $this->config->get('config_replace_cart_button');
		$data['replace_cart_button_text'] = $this->config->get('config_replace_cart_button_text');
		]]></add>
	</operation>
</file>

тут все по отдельности, поэтому статус замены мы можем объединить. Условие будет такое что кол-во не больше 0 и в админке мы включили настройку, нет смысла в шаблоне делать условия, старайтесь все вообще максимально упрощать в разумных пределах

$data['replace_cart_button_status'] = $this->config->get('config_replace_cart_button') && $product_info['quantity'] <= 0 ;

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

Будем считать что мы нашли уникальный элемент во всех шаблонах и используем путь

catalog/view/theme/*/template/product/product.tpl

Поищем кнопку купить

<button type="button" id="button-cart" data-loading-text="<?php echo $text_loading; ?>" class="btn btn-primary btn-lg btn-block"><?php echo $button_cart; ?></button>

Пробуем <?php echo $button_cart; ?> , не подходит, оно используется еще в рекомендуемых товарах и если изменится кнопка в товаре - на всех рекомендуемых получим "под заказ"

Заменим все целиком и там где название просто выведем нужный текст в зависимости от наших условий, лучше использовать короткий if чтобы оно и смотрелось нормально и не нагромождать if else и тп в и без того длинной строчке

<file path="catalog/view/theme/*/template/product/product.tpl"> 
	<operation error="skip">
		<search><![CDATA[<button type="button" id="button-cart" data-loading-text="<?php echo $text_loading; ?>" class="btn btn-primary btn-lg btn-block"><?php echo $button_cart; ?></button>]]></search>
		<add position="replace"><![CDATA[<button type="button" id="button-cart" data-loading-text="<?php echo $text_loading; ?>" class="btn btn-primary btn-lg btn-block"><?php echo $replace_cart_button_status ? $replace_cart_button_text : $button_cart; ?></button>]]></add>
	</operation>
</file>

обратите внимание - replace - тупо заменяет искомое на требуемое, поэтому я рекомендую если вы меняете что-то в одной строке или ее части, так тоже можно - смотрите чтобы оно было без пробелов и переносов, т.к. поломаете верстку и вас никто не будет любить. Также с большой осторожностью используйте offset в replace - он заменяет нижние строки полностью, потренируйтесь на каком-то простом файле

Вуаля. Опять работает когда количество 0

Ну, мы уже опытные модулеписатели. Айда провернем то же самое в категориях

А заодно на страничке товаров производителя, поиске и акциях, т.к. контроллеры и шаблоны у них практически идентичны

А еще заодно в рекомендуемых товарах на страничке самого товара

<file path="catalog/controller/product/*.php">	

это значит мы будем искать во всех контроллерах в папке product

можно и так

<file path="catalog/controller/product/{category,manufacturer,search,special,product}.php">	

Напомню, нам нужно получить статус замены текста на кнопке и, собственно, сам текст

Итого 5 контроллеров, ищем строки которые встречаются во всех

Возьмем к примеру 

'name'        => $result['name'],

это название товара, встречается везде, навредить мы не сможем

<file path="catalog/controller/product/*.php"> 
	<operation error="skip">
		<search><![CDATA['name'        => $result['name'],]]></search>
		<add position="after"><![CDATA[ 
		'replace_cart_button_status'        => $this->config->get('config_replace_cart_button') && $result['quantity'] <= 0,
		'replace_cart_button_text'          => $this->config->get('config_replace_cart_button_text'),
		]]></add>
	</operation>
</file>

Сразу скажу что это не лучший вариант, текст и статус модификации лучше получить где-то до этого цикла товаров и в шаблоне использовать переменные, но наша сейчас цель - понять как работают модификаторы и мы немного уже углубились) Теперь каждый товар будет знать заменять ли текст на кнопке и если заменять то на какой

Точно так же ищем кнопку "купить" и заменяем ее на похожую конструкцию за исключением того что у нас будет не просто $replace_cart_button_status а $product['replace_cart_button_status']. В нормальных шаблонах эти места одинаковые, поэтому будем считать что у нас идеальные условия.

<file path="catalog/view/theme/*/template/product/*.tpl"> 
	<operation error="skip">
		<search><![CDATA[<button type="button" onclick="cart.add('<?php echo $product['product_id']; ?>', '<?php echo $product['minimum']; ?>');"><i class="fa fa-shopping-cart"></i> <span class="hidden-xs hidden-sm hidden-md"><?php echo $button_cart; ?></span></button>]]></search>
		<add position="replace"><![CDATA[<button type="button" onclick="cart.add('<?php echo $product['product_id']; ?>', '<?php echo $product['minimum']; ?>');"><i class="fa fa-shopping-cart"></i> <span class="hidden-xs hidden-sm hidden-md"><?php echo $product['replace_cart_button_status'] ? $product['replace_cart_button_text'] : $button_cart; ?></span></button>]]></add>
	</operation>
</file>

вуаля

Упс, в карточке товара рекомендуемые используют чуть другой код (разницы в 1 символе хватит чтобы мод не сработал), ничего, мы добавим аналогичную операцию к product.tpl

	<operation error="skip">
		<search><![CDATA[<button type="button" onclick="cart.add('<?php echo $product['product_id']; ?>', '<?php echo $product['minimum']; ?>');"><span class="hidden-xs hidden-sm hidden-md"><?php echo $button_cart; ?></span> <i class="fa fa-shopping-cart"></i></button>]]></search>
		<add position="replace"><![CDATA[<button type="button" onclick="cart.add('<?php echo $product['product_id']; ?>', '<?php echo $product['minimum']; ?>');"><span class="hidden-xs hidden-sm hidden-md"><?php echo $product['replace_cart_button_status'] ? $product['replace_cart_button_text'] : $button_cart; ?></span> <i class="fa fa-shopping-cart"></i></button>]]></add>
	</operation>

Как-то это сильно просто

Давайте добавим то же самое еще и в модули

В опенкарте 4 стандартных дефолтных модуля (последние, рекомендуемые, хиты продаж и акции), проделываем с ними то же самое

О, ухты! В модулях используется для названия товара то же самое

'name'        => $result['name'],

Сделаем по-умному, изменим путь контроллера там где делали в категориях на

<file path="catalog/controller/{extension/module,product}/*.php"> 

и теперь модификатор поищет по обоим путям и добавит переменные везде где нам нужно

С шаблоном такое не прокатило, для модулей делаем отдельно

<file path="catalog/view/theme/*/template/extension/module/*.tpl"> 
	<operation error="skip">
		<search><![CDATA[<button type="button" onclick="cart.add('<?php echo $product['product_id']; ?>');"><i class="fa fa-shopping-cart"></i> <span class="hidden-xs hidden-sm hidden-md"><?php echo $button_cart; ?></span></button>]]></search>
		<add position="replace"><![CDATA[<button type="button" onclick="cart.add('<?php echo $product['product_id']; ?>');"><i class="fa fa-shopping-cart"></i> <span class="hidden-xs hidden-sm hidden-md"><?php echo $product['replace_cart_button_status'] ? $product['replace_cart_button_text'] : $button_cart; ?></span></button>]]></add>
	</operation>
</file>

Все сделали и ой

Почему-то это еще с версии 1.5 живет и никто не осмеливается это менять

в контроллере рекомендуемых - не $result а $product_info

Делаем исключение и добавляем туда отдельно

<file path="catalog/controller/extension/module/featured.php"> 
	<operation error="skip">
		<search><![CDATA['name'        => $product_info['name'],]]></search>
		<add position="after"><![CDATA[ 
		'replace_cart_button_status'        => $this->config->get('config_replace_cart_button') && $product_info['quantity'] <= 0,
		'replace_cart_button_text'          => $this->config->get('config_replace_cart_button_text'),
		]]></add>
	</operation>
</file>   

Все работает, и это было совсем не больно

И вот у нас уже готовый модификатор который немного изменив под свои хотелки можно продать за 300р))

super_mod.ocmod.xml

Итого краткое резюме:

- Всегда проверяйте свое условие search чтобы оно было уникальным и никому не мешало, не привязывайтесь к $category_info или $data['heading_title']

- Используйте offset осторожно, а в replace вообще не используйте

- Старайтесь использовать меньшее количество кода, но оставляйте его читаемым

- есть еще search regex но это совсем другая история

Если что-то сломалось после применения модификатора из папки system нужно всего лишь переименовать его, скажем, в .ocmod.xml_ , т.е. изменить расширение и обновить кеш модификаторов

Если сломалась страница обновления модификаторов - нужно очистить папку storage/modification (путь к ней можно подглядеть в config.php) тогда, страничка откроется

Это работает если ничего не правилось в кеше модификаторов - но  у кого так - тот и сам знает все боли и их не обновляет

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

Спасибо за внимание, ваш spectre