Создание собственных автоматизированных обработчиков служб доставки

В этом разделе

Структура обработчика

Автоматизированные обработчики служб доставки позволяют программным образом реализовать произвольную логику расчёта стоимости доставки на основе параметров заказа и собственных настроек. Алгоритмы расчёта могут быть произвольными - фиксированная стоимость, запросы к удаленным web-сервисам, расчёт на основе собственных таблиц данных и т.д.

Обработчик представляет собой класс или набор функций следующей структуры:

Поскольку работать с набором отдельных функций неудобно, рекомендуется объединить их в класс (пространство имен). Исходя из этой рекомендации будет идти дальнейшее описание, а также, реализован приводимый пример. В примере обработчик "Курьерская доставки" реализован в виде класса CDeliveryMySimple.

Описание обработчика

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

Описание профилей представляет собой массив следующего формата:

"строковой_идентификато_профиля" => array(
	"TITLE" => "название_профиля",
	"DESCRIPTION" => "описание_профиля",
	// веса указываются в граммах
	"RESTRICTIONS_WEIGHT" => array(минимальный_вес, максимальный_вес), 
	// суммы указываются в базовой валюте обработчика
	"RESTRICTIONS_SUM" => array(минимальная_сумма_заказа, максимальная_сумма_заказа)
);

Если массив RESTRICTIONS_WEIGHT или RESTRICTIONS_SUM содержит один элемент, то он считается минимальным значением. Если никаких ограничений не требуется, нужно указать array(0).

Пример:

function Init()
{
	return array(
		/* Basic description */
		"SID" => "simple",
		"NAME" => "Доставка курьером",
		"DESCRIPTION" => "",
		"DESCRIPTION_INNER" => 
"Простой обработчик курьерской доставки. Для функционирования необходимо "
."наличие хотя бы одной группы местоположений. При настройке обработчика указывается "
."фиксированная стоимость доставки для каждой группы местоположений. Для того, чтобы "
."группа не участвовала в обработке, оставьте пустым поле стоимости для этой группы."
."<br />"
."<a href=\"/bitrix/admin/sale_location_group_admin.php?lang=ru\" target=\"_blank\">"
."Редактировать группы местоположений"
."</a>.",
		"BASE_CURRENCY" => COption::GetOptionString("sale", "default_currency", "RUB"),

		"HANDLER" => __FILE__,
    
		/* Handler methods */
		"DBGETSETTINGS" => array("CDeliveryMySimple", "GetSettings"),
		"DBSETSETTINGS" => array("CDeliveryMySimple", "SetSettings"),
		"GETCONFIG" => array("CDeliveryMySimple", "GetConfig"),
    
		"COMPABILITY" => array("CDeliveryMySimple", "Compability"),      
		"CALCULATOR" => array("CDeliveryMySimple", "Calculate"),      
    
		/* List of delivery profiles */
		"PROFILES" => array(
			"simple" => array(
				"TITLE" => "доставка",
				"DESCRIPTION" => "Срок доставки до 3 дней",
        
				"RESTRICTIONS_WEIGHT" => array(0),
				"RESTRICTIONS_SUM" => array(0),
			),
		)
	);
}

Параметры валидатора

Метод, заданный элементом GETCONFIG, должен возвращать массив элементов вида:

array(
	"CONFIG_GROUPS" => array(
	"идентификатор_группы1" => "название_группы1",
	"идентификатор_группы2" => "название_группы2",
	/* ...................... */
	),
	"CONFIG" => array(
		"идентфикатор_параметра1" => array(
			"TITLE" = > "название_параметра1",
			"TYPE" => "тип_параметра1",
			"DEFAULT" => "значение_по_умолчанию_параметра1",
			"GROUP" => "идентфикатор_группы_параметра1",
			"VALUES" => array(
				"значение1_параметра1" => "наименование_значения1_параметра1",
				"значение2_параметра1" => "наименование_значения2_параметра1",
				/* ....................... */
			)
		),

		/* ........................ */
	)
)

Группы параметров, описываемые в элементе массива с ключом "CONFIG_GROUPS" отображаются в виде отдельных вкладок в форме редактирования параметров обработчика, содержащих параметры, приписанные к этой группе. Элемент массива с ключом "CONFIG" задает список параметров. Тип параметра может принимать одно из следующих значений:

• STRING - поле для ввода текста
• PASSWORD - поле для ввода пароля
• CHECKBOX - элемент типа "флажок" со значением 'Y'
• RADIO - набор вариантов в виде радио-кнопок
• DROPDOWN - набор вариантов в виде выпадающего списка
• MULTISELECT - набор вариантов в виде списка со множественным выбором
• RADIO - набор вариантов в виде радио-кнопок

Для типов параметра подразумевающий выбор из нескольких вариантов значений (DROPDOWN, MULTISELECT и RADIO) список значений задается элементом описательного массива с ключом "VALUES". Для остальных типов параметров этот элемент игнорируется.

Пример:

function GetConfig()
{
	$arConfig = array(
		"CONFIG_GROUPS" => array(
			"all" => "Стоимость доставки",
		),
    
		"CONFIG" => array(),
  	);

	// параметрами обработчика в данном случае являются значения стоимости доставки в различные группы местоположений.
	// для этого сформируем список параметров на основе списка групп
	$dbLocationGroups = CSaleLocationGroup::GetList();
	while ($arLocationGroup = $dbLocationGroups->Fetch())
	{
		$arConfig["CONFIG"]["price_".$arLocationGroup["ID"]] = array(
			"TYPE" => "STRING",
			"DEFAULT" => "",
			"TITLE" => 
			"Стоимость доставки в группу "\" "
			$arLocationGroup["NAME"]."\" "
			(".COption::GetOptionString("sale", "default_currency", "RUB").')',
			"GROUP" => "all",
		);
	}
  
	return $arConfig; 
}

Обработка параметров

Обработка параметров обработчика требует двух методов, задаваемых в описании параметрами DBSETSETTINGS и DBGETSETTINGS. Первый из них получает на вход массив значений параметров вида "идентфикатор_параметра" => "значение_параметра" и должен вернуть их строковое представление. Второй - совершить обратное преобразование. Оба метода могут также совершать произвольные манипуляции со значениями параметров.

Пример:

	
function SetSettings($arSettings)
{
	// Проверим список значений стоимости. Пустые значения удалим из списка.
	foreach ($arSettings as $key => $value) 
	{
		if (strlen($value) > 0)
			$arSettings[$key] = doubleval($value);
		else
			unset($arSettings[$key]);
	}

	// вернем значения в виде сериализованного массива.
	// в случае более простого списка настроек можно применить более простые методы сериализации.
	return serialize($arSettings);
}

function GetSettings($strSettings)
{
	// вернем десериализованный массив настроек
	return unserialize($strSettings);
}

Проверка совместимости

Проверка совместимости профилей обработчика с заказом осуществляется методом, задаваемым в описании параметром "COMPABILITY". Этот метод принимает на вход 2 параметра - описательный массив заказа и массив настроек обработчика. В качестве ответа метода ожидается массив, содержащий идентификаторы подходящих для данного заказа профилей доставки. Проверка, задаваемая значениями "RESTRICTIONS_WEIGHT" и "RESTRICTIONS_SUM" в настройках профиля, производится вне обработчика и здесь не требуется. Формат принимаемых на вход данных следующий:

Первый параметр - информация о заказе - представляет собой массив со следующими ключами:

Второй параметр представляет собой значение массива, заданного элементом с ключом "CONFIG" в списке настроек обработчика, к каждому элементу которого добавлено значение параметра с ключом "VALUE".

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

Пример:

// введем служебный метод, определяющий группу местоположения и возвращающий стоимость для этой группы.
function __GetLocationPrice($LOCATION_ID, $arConfig)
{
	// получим список групп для переданного местоположения
	$dbLocationGroups = CSaleLocationGroup::GetLocationList(array("LOCATION_ID" => $LOCATION_ID));
  
	while ($arLocationGroup = $dbLocationGroups->Fetch())
	{
		if (
			array_key_exists('price_'.$arLocationGroup["LOCATION_GROUP_ID"], $arConfig) 
			&& 
			strlen($arConfig['price_'.$arLocationGroup["LOCATION_GROUP_ID"]]["VALUE"] > 0)
		)
		{
			// если есть непустая запись в массиве настроек для данной группы, вернем ее значение
			return $arConfig['price_'.$arLocationGroup["LOCATION_GROUP_ID"]]["VALUE"];
		}
	}

	// если не найдено подходящих записей, вернем false
	return false;
}

// метод проверки совместимости в данном случае практически аналогичен рассчету стоимости
function Compability($arOrder, $arConfig)
{
	// проверим наличие стоимости доставки
	$price = CDeliveryMySimple::__GetLocationPrice($arOrder["LOCATION_TO"], $arConfig);
  
	if ($price === false)
		return array(); // если стоимость не найдено, вернем пустой массив - не подходит ни один профиль
	else
		return array('simple'); // в противном случае вернем массив, содержащий идентфиикатор единственного профиля доставки
}

Обработчик

Основной метод расчёта стоимости доставки получает на вход следующие параметры:

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

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

В описываемом нами примере многошаговый процесс не подразумевается, потому, расчёт осуществляется просто.

Пример:

function Calculate($profile, $arConfig, $arOrder, $STEP, $TEMP = false)
{
	// служебный метод рассчета определён выше, нам достаточно переадресовать на выход возвращаемое им значение.
	return array(
		"RESULT" => "OK",
		"VALUE" => CDeliveryMySimple::__GetLocationPrice($arOrder["LOCATION_TO"], $arConfig)
	);
}

Интеграция обработчика

Путь к автоматически подключаемым файлам обработчиков устанавливается в настройках модуля "Интернет-магазин". Путь по умолчанию - /bitrix/php_interface/include/sale_delivery/ Такие файлы должны иметь префикс delivery_, в противном случае, они будут проигнорированы. Если система обнаружит файл, имеющее то же название, что и системный, то он будет подключаться вместо системного. Подключение автоматизированной доставки в файле производится установкой описательного метода в качестве обработчика события onSaleDeliveryHandlersBuildList.

Пример

Подытожив все вышесказанное, сформируем обработчик простой доставки. Класс обработчика расположим в файле /bitrix/php_interface/include/sale_delivery/delivery_mysimple.php

<?
// Листинг файла /bitrix/php_interface/include/sale_delivery/delivery_mysimple.php

CModule::IncludeModule("sale");

class CDeliveryMySimple
{
	function Init()
	{
		return array(
			/* Основное описание */
			"SID" => "simple", 
			"NAME" => "Доставка курьером",
			"DESCRIPTION" => "",
			"DESCRIPTION_INNER" => 
"Простой обработчик курьерской доставки. Для функционирования необходимо "
."наличие хотя бы одной группы местоположений. При настройке обработчика указывается "
."фиксированная стоимость доставки для каждой группы местоположений. Для того, чтобы "
."группа не участвовала в обработке, оставьте пустым поле стоимости для этой группы."
."<br />"
."<a href=\"/bitrix/admin/sale_location_group_admin.php?lang=ru\" target=\"_blank\">"
."Редактировать группы местоположений"
."</a>.",
			"BASE_CURRENCY" => COption::GetOptionString("sale", "default_currency", "RUB"),

			"HANDLER" => __FILE__,
      
			/* Методы обработчика */
			"DBGETSETTINGS" => array("CDeliveryMySimple", "GetSettings"),
			"DBSETSETTINGS" => array("CDeliveryMySimple", "SetSettings"),
			"GETCONFIG" => array("CDeliveryMySimple", "GetConfig"),
      
			"COMPABILITY" => array("CDeliveryMySimple", "Compability"),      
			"CALCULATOR" => array("CDeliveryMySimple", "Calculate"),      
      
			/* Список профилей доставки */
			"PROFILES" => array(
				"simple" => array(
					"TITLE" => "доставка",
					"DESCRIPTION" => "Срок доставки до 3 дней",
          
					"RESTRICTIONS_WEIGHT" => array(0), // без ограничений
					"RESTRICTIONS_SUM" => array(0), // без ограничений
				),
			)
		);
	}

	// настройки обработчика
	function GetConfig()
	{
		$arConfig = array(
			"CONFIG_GROUPS" => array(
				"all" => "Стоимость доставки",
			),
      
			"CONFIG" => array(),
		);

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

		$dbLocationGroups = CSaleLocationGroup::GetList();
		while ($arLocationGroup = $dbLocationGroups->Fetch())
		{
			$arConfig["CONFIG"]["price_".$arLocationGroup["ID"]] = array(
				"TYPE" => "STRING",
				"DEFAULT" => "",
				"TITLE" => 
				"Стоимость доставки в группу \""
				$arLocationGroup["NAME"]."\" "
				"(".COption::GetOptionString("sale", "default_currency", "RUB").')',
				"GROUP" => "all",
			);
		}
    
		return $arConfig; 
	}

	// подготовка настроек для занесения в базу данных
	function SetSettings($arSettings)
	{
		// Проверим список значений стоимости. Пустые значения удалим из списка.
		foreach ($arSettings as $key => $value) 
		{
			if (strlen($value) > 0)
				$arSettings[$key] = doubleval($value);
			else
				unset($arSettings[$key]);
		}

		// вернем значения в виде сериализованного массива.
		// в случае более простого списка настроек можно применить более простые методы сериализации.
		return serialize($arSettings);
	}

	// подготовка настроек, полученных из базы данных
	function GetSettings($strSettings)
	{
		// вернем десериализованный массив настроек
		return unserialize($strSettings);
	}
    
	// введем служебный метод, определяющий группу местоположения и возвращающий стоимость для этой группы.
	function __GetLocationPrice($LOCATION_ID, $arConfig)
	{
		// получим список групп для переданного местоположения
		$dbLocationGroups = CSaleLocationGroup::GetLocationList(array("LOCATION_ID" => $LOCATION_ID));
    
		while ($arLocationGroup = $dbLocationGroups->Fetch())
		{
			if (
				array_key_exists('price_'.$arLocationGroup["LOCATION_GROUP_ID"], $arConfig) 
				&& 
				strlen($arConfig['price_'.$arLocationGroup["LOCATION_GROUP_ID"]]["VALUE"] > 0)
			)
			{
			// если есть непустая запись в массиве настроек для данной группы, вернем ее значение
			return $arConfig['price_'.$arLocationGroup["LOCATION_GROUP_ID"]]["VALUE"];
			}
		}

		// если не найдено подходящих записей, вернем false
		return false;
	}

	// метод проверки совместимости в данном случае практически аналогичен рассчету стоимости
	function Compability($arOrder, $arConfig)
	{
		// проверим наличие стоимости доставки
		$price = CDeliveryMySimple::__GetLocationPrice($arOrder["LOCATION_TO"], $arConfig);
    
		if ($price === false)
			return array(); // если стоимость не найдено, вернем пустой массив - не подходит ни один профиль
		else
			return array('simple'); // в противном случае вернем массив, содержащий идентфиикатор единственного профиля доставки
	}
    
	// собственно, рассчет стоимости
	function Calculate($profile, $arConfig, $arOrder, $STEP, $TEMP = false)
	{
		// служебный метод рассчета определён выше, нам достаточно переадресовать на выход возвращаемое им значение.
		return array(
			"RESULT" => "OK",
			"VALUE" => CDeliveryMySimple::__GetLocationPrice($arOrder["LOCATION_TO"], $arConfig)
		);
	}
}

// установим метод CDeliveryMySimple::Init в качестве обработчика события
AddEventHandler("sale", "onSaleDeliveryHandlersBuildList", array('CDeliveryMySimple', 'Init')); 
?>

Post factum

Несколько советов в завершение:

• Если Ваш обработчик использует какие-либо ресурсоемкие вычисления, обращения к базе данных, запросы к удаленным серверам и т.д., то категорически рекомендуется использовать тот или иной вариант кеширования результата, реализованный таким образом, чтобы запоминались результаты хотя бы для заказа с данными параметрами. Это необходимо из-за того, что в процессе оформления и обработки заказа запрос к обработчику на расчёт стоимости заказа может происходить несколько раз. В поставляемых обработчиках используется механизм управляемого кеширования, настроенный с учётом специфики алгоритма вычисления стоимости конкретной службой доставки.
• Для кастомизации системного обработчика достаточно скопировать его файл (вместе с сопутствующими файлами, лежащими обычно в каталоге с тем же названием) в каталог /bitrix/php_interface/include/sale_deivery/ с сохранением имени. В этом случае он будет подключаться вместо системного.

См. также