msCurrency — мультивалютность для MODX Revolution 3 и MiniShop3

msCurrency добавляет мультивалютность в магазин на MiniShop3 и MODX 3: переключатель на витрине, курсы из ЦБ и других источников, цена товара в своей валюте, корзина в валюте покупателя, фиксация валюты в заказе, фильтр mFilter, передача кода валюты в платёжку.

В менеджере — справочник валют и Vue 3-дашборд котировок. На витрине — пересчёт цен, корзины и заказа.

Настройка mscurrency_ajax_switch обновляет цены и корзину без перезагрузки страницы.

Сниппеты

Все примеры ниже — в синтаксисе Fenom (pdoTools).

msCurrency

Переключатель валют на витрине.

{'!msCurrency' | snippet}
{'!msCurrency' | snippet : ['tpl' => 'tpl.msCurrencySelect']}
{'!msCurrency' | snippet : ['compact' => 1]}
{'!msCurrency' | snippet : ['showLabel' => 0]}
{'!msCurrency' | snippet : ['tpl' => '']}

msCurrencyPrice

Цена товара в валюте, которую выбрал покупатель.

{'!msCurrencyPrice' | snippet : ['pid' => $_modx->resource.id, 'format' => 1]}
{'!msCurrencyPrice' | snippet : ['price' => $price, 'pid' => $_modx->resource.id, 'format' => 1]}
<div class="msc-price-display">
  {'!msCurrencyPrice' | snippet : ['pid' => $_modx->resource.id, 'format' => 1]}
</div>

msCurrencyPrices

Цены одного товара во всех активных валютах магазина.

{'!msCurrencyPrices' | snippet : ['pid' => $_modx->resource.id, 'symbol' => 'left']}
{'!msCurrencyPrices' | snippet : ['tpl' => 'tpl.msCurrencyPrices', 'pid' => $_modx->resource.id]}

msCurrencyCart

Обёртка над ms3_cart с валютным контекстом.

<div id="demo-cart">
  {'!msCurrencyCart' | snippet : [
      'tpl' => 'tpl.cartWrapper',
      'cartTpl' => 'tpl.msCart',
      'selector' => '#demo-cart'
  ]}
</div>

В строках корзины: {$product.price_formatted}, {$product.cost_formatted}, {$currency}.

msCurrencyGetOrder

Показывает оформленный заказ на странице «Спасибо за заказ» и в личном кабинете. Обёртка над стандартным ms3_get_order MiniShop3: те же позиции и суммы, но символы и формат цен соответствуют валюте, в которой покупатель оформил заказ.
Куда вставить: шаблон страницы успешного оформления, куда MS3 перенаправляет после checkout. MS3 записывает ID заказа в плейсхолдер msorder. Его и передаём в сниппет.

Минимальный вызов, если чанк заказа уже настроен в MiniShop3:

{'!msCurrencyGetOrder' | snippet : ['id' => $_modx->getPlaceholder('msorder')]}

Свои чанки, если нужна обёртка с кодом валюты рядом с блоком заказа:

• id — номер заказа, $_modx->getPlaceholder('msorder') после оформления
• orderTpl — чанк заказа MS3 (список товаров, итого), тот же, что для ms3_get_order
• tpl — обёртка: {$currency} (код валюты) и {$output} (HTML из orderTpl)

{'!msCurrencyGetOrder' | snippet : [
    'id' => $_modx->getPlaceholder('msorder'),
    'tpl' => 'tpl.orderWrapper',
    'orderTpl' => 'tpl.msGetOrder'
]}

При оформлении в properties заказа сохраняются код валюты, символы и курс на момент покупки. В чанке заказа и в письме покупателю:

{$order.properties.msc.code}
{$order.properties.msc.symbol_left}
{$order.properties.msc.symbol_right}
{$order.properties.msc.val}

Те же поля дублируются в properties.msmc. Сумма и валюта в истории заказа не пересчитываются, если курс изменится позже.

mscLexiconScript

Выводит JSON лексикона msCurrency для JavaScript на витрине.

{'!mscLexiconScript' | snippet}

AJAX

Настройка mscurrency_ajax_switch. После смены валюты JavaScript обновляет блоки [data-msc-price], контейнеры из selector и вызывает mfilter.reload(). Без JavaScript страница перезагружается целиком.

Корзина: base / user

Режим задаётся настройкой mscurrency_order_price_mode:

• base — суммы в базовой валюте каталога
• user — суммы в валюте покупателя. Плагин mscurrency_cart_display пересчитывает корзину на событиях msOnGetCart, msOnGetStatusCart, msOnGetCartCost

Курсы

Источники: ЦБ РФ, НБУ, НБРБ, НБК, ECB. В дашборде видны время последней синхронизации, изменение курса и устаревшие котировки.

php core/components/mscurrency/cron/sync_rates.php

Свой поставщик курсов. Скопируйте providers/ExampleStaticRateProvider.php, переименуйте класс и положите файл в core/components/mscurrency/providers/ (namespace mscurrency\Providers\). Класс наследует AbstractMscRateProvider: задаёте ключ, валюту котировок, список кодов и метод получения курса. В панеле управления откройте Поставщики курсов → Добавить поставщика, выберите класс и сохраните. На вкладке Привязки сопоставьте внешний код API с валютой сайта (например USD у Fixer → USD в справочнике). Без привязок sync ищет совпадение по коду валюты. Встроенным ЦБ/ECB/НБУ ключ не нужен. Для платного API ключ храните в системной настройке MODX или в properties записи поставщика.
Округление цен задаётся отдельно для каждой валюты в справочнике (price_rounding). Применяется при конвертации на витрине: сниппеты, корзина, getPrice().

• none — без дополнительного правила, только точность до копеек
• round — математическое округление
• ceil — всегда вверх (удобно, если не хотите занижать цену)
• floor — всегда вниз
• to_99 — цены от 1 и выше к виду 1234.99 (как в типовых витринах с «психологической» ценой)

GeoIP, mFilter, контексты, платёжка

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

{'!mFilter' | snippet : ['filters' => 'ms3_product|price:currency_price']}

Для контекста: mscurrency_selected_currency_default — ID валюты по умолчанию. В сетке категории MS3 добавьте currency_id, msc_price, msc_old_price в ms3_category_grid_fields.
Плагин mscurrency_payment_currency и ключ mscurrency_payment_currency_option передают код валюты заказа в опцию платёжного модуля.

Стек

• MODX Revolution 3.0+, PHP 8.2+, MiniShop3, pdoTools 3.x
• mFilter и платёжные дополнения MS3 — по желанию

Пакет в ModStore msCurrency. Документация: docs.modx.pro/components/mscurrency.
Демо: demo.ibochkarev.su/demo/mscurrency-test.html.