msCurrency

msCurrency — дополнение для MODX Revolution 3 и MiniShop3: несколько валют на витрине, автоматические курсы, цена товара в своей валюте, корзина и заказ с учётом выбора покупателя.

С чего начать: Быстрый старт.

Минимальный путь на витрине

1. Установить MiniShop3 и msCurrency через ModStore.
2. Открыть MiniShop3 → Валюты (msCurrency), проверить справочник и нажать Синхронизировать курсы.
3. В шаблоне сайта вывести переключатель (см. Быстрый старт).
4. На карточке товара заменить вывод цены на msCurrencyPrice (см. Быстрый старт).
5. Очистить кэш и проверить смену валюты на карточке. В оформленном заказе должен быть снимок properties.msc.

Быстрые ссылки

Нужно	Документ
Установить и вывести переключатель	Быстрый старт
Все ключи mscurrency_*	Системные настройки
Сниппеты и параметры	Сниппеты
Карточка, корзина, заказ, платёжки	Интеграция
CRUD валют, cron, connector	Управление валютами
mscOnGetPrice, mscOnToggleCurrency	События MODX
Фильтр по цене в валюте пользователя	mFilter
GeoIP, AJAX без reload	Интеграция, Настройки
Диагностика	FAQ

Возможности

• Справочник валют — базовая валюта, коэффициент, поле val (курс × коэффициент), округление цены per currency (price_rounding, в т.ч. to_99)
• Поставщики курсов — ЦБ РФ, ECB (EUR), НБУ, НБРБ, НБК и свои классы. Cron: sync_rates.php
• Дашборд курсов — KPI, журнал sync, Δ курса, устаревшие котировки (mscurrency_stale_rate_days)
• Переключатель на витрине — чанки tpl.msCurrency (ссылки), tpl.msCurrencySelect (<select>), tpl.msCurrencyCompact (компактный вид); плейсхолдеры msc.* / msmc.*
• AJAX-смена валюты (opt-in, mscurrency_ajax_switch) — обновление [data-msc-price] без reload
• GeoIP (opt-in) — автовыбор валюты по стране, плагин mscurrency_detect
• Цена товара в отдельной валюте — поля currency_id, msc_price, msc_old_price в карточке MS3
• Режим заказа — суммы в базовой валюте или в валюте покупателя (mscurrency_order_price_mode)
• Снимок валюты в заказе — properties.msc (и дубль msmc) при оформлении
• Админка Vue 3 — CRUD валют, провайдеры, привязки, синхронизация курсов
• mFilter — тип фильтра currency_price (опционально)

Системные требования

Требование	Версия
MODX Revolution	3.0+
PHP	8.2+
MiniShop3	1.0+
pdoTools	3.0+ (рекомендуется для Fenom)
VueTools	для Vue-админки msCurrency

Зависимости

• MiniShop3 — товары, корзина, заказы, формат цены

Опционально

• mFilter — фильтр каталога currency_price
• VueTools — без него админка msCurrency покажет предупреждение и не загрузит UI

Установка

1. Подключите репозиторий ModStore.
2. Extras → Installer → Download Extras — найдите msCurrency, Download, Install.
3. Убедитесь, что установлен MiniShop3 (и VueTools для админки).
4. Настройте область mscurrency в системных настройках.
5. Настройки → Очистить кэш.

Каталог: modstore.pro/packages/ecommerce/mscurrency.

После установки появляются:

• namespace mscurrency
• сниппеты msCurrency, msCurrencyPrice, msCurrencyPrices, msCurrencyCart, msCurrencyGetOrder, mscLexiconScript
• чанки tpl.msCurrency, tpl.msCurrencySelect, tpl.msCurrencyCompact, tpl.msCurrencyPrices
• плагины категории msCurrency
• таблицы msc_currency, msc_providers, msc_provider_links
• файл core/config/ms3.services.d/50-mscurrency.php

Термины

Термин	Описание
Базовая валюта	Валюта каталога MS3. Поле price товара хранится в ней (обычно RUB)
val	Эффективный курс: rate × coefficient. Цена на витрине: база ÷ val
Снимок валюты	Массив в order.properties.msc: код, символы, val на момент заказа
Режим user	Корзина и заказ показывают суммы в выбранной валюте покупателя
Режим base	Суммы в базовой валюте. Переключатель влияет только на отображение на витрине

Архитектура (кратко)

Подробнее: Интеграция, События MODX, Управление валютами.