msGiftCards

msGiftCards — дополнение для MODX Revolution 2 + miniShop2 для продажи, применения, учета и управления подарочными сертификатами.

ВАЖНО!!!
Перед установкой на боевой проект обязательно сделать бэкапы!!!

Ключевые возможности:

— Генерация сертификатов по статусу заказа (msgiftcards_generate_status_id).
— Применение сертификата на оформлении заказа.
— Частичное списание сертификата.
— Автоматический пересчет сертификата при изменении корзины.
— Списание по статусу заказа (msgiftcards_paid_status_id).
— Возврат суммы на сертификат при отмене заказа (msgiftcards_cancel_status_id).
— Управление сертификатами и историей операций в менеджере MODX.
— Генерация защищенной ссылки на PDF сертификата.
— Генерация PDF из HTML-чанка через встроенную библиотеку dompdf.

Совместимость

— MODX Revolution 2.x
— miniShop2
— PHP 7.4+
— Совместимо с msPromoCode2 и msBonus2

Установка

— Установите пакет msgiftcards-*.transport.zip через установщик MODX.
— Очистите кэш MODX.
— Настройте системные параметры в namespace msgiftcards.

Системные настройки

Основные:

msgiftcards_enabled — глобальное включение дополнения.
msgiftcards_nominal_option — ключ опции товара с номиналом сертификата.
msgiftcards_default_currency — валюта сертификата по умолчанию.
msgiftcards_certificate_lifetime_days — срок действия сертификата в днях (0 = без срока).
msgiftcards_generate_status_id — статус заказа для генерации сертификата.
msgiftcards_paid_status_id — статус заказа для списания сертификата.
msgiftcards_cancel_status_id — статус заказа для возврата суммы на сертификат.
msgiftcards_gift_payment_id — ID способа оплаты «Подарочный сертификат» для заказов с итогом 0.

Генерация кода:

msgiftcards_code_mask — маска генерации кода сертификата.

Безопасность:

msgiftcards_certificate_token_key — секретный ключ для шифрования и подписи ссылок на PDF сертификата. Создается автоматически при первой установке и не должен меняться.

PDF:

msgiftcards_certificate_pdf_paper — формат листа PDF сертификата. По умолчанию: A5.
msgiftcards_certificate_pdf_orientation — ориентация PDF сертификата. По умолчанию: landscape.

Сниппеты

msGiftCardsField — поле применения сертификата на checkout.
msGiftCardsInfo — блок информации о примененном сертификате.
msGiftCardsOrderData — данные сертификатов и операций по order_id.
msGiftCardsCertificateLink — генерация защищенной ссылки на HTML/PDF сертификата.
msGiftCardsCertificateHtml — генерация HTML сертификата по чанку.

Параметры msGiftCardsOrderData:

order_id — ID заказа.
mode — all, issued, redeemed.
format — json, array.
toPlaceholder — сохранить результат в плейсхолдер.
includeIssuedRedemptions — включать операции в блок issued.

Параметры msGiftCardsCertificateLink:

order_id — ID заказа.
toPlaceholder — сохранить ссылку в плейсхолдер.
format — pdf или html.
tpl — альтернативный чанк/@FILE шаблон для certificate.php.

Параметры msGiftCardsCertificateHtml:

order_id — ID заказа.
token — защищенный токен вместо открытого order_id.
tpl — чанк или @FILE шаблон сертификата.
toPlaceholder — сохранить HTML в плейсхолдер.

Чанки

msGiftCards.field
msGiftCards.info
msGiftCards.certificate
msGiftCards.certificate используется:
— для HTML-preview сертификата;
— для PDF, который отдает assets/components/msgiftcards/certificate.php.

Шаблон сертификата по умолчанию:

— рассчитан под A5 landscape;
— использует DejaVu Sans для корректного PDF с кириллицей;
— правится полностью через чанк.

Примеры использования

Обычный MODX:

[[!msGiftCardsField]]
[[!msGiftCardsInfo]]
[[!msGiftCardsOrderData? &order_id=123 &mode=all]]
[[!msGiftCardsCertificateLink? &order_id=123]]
[[!msGiftCardsCertificateHtml? &order_id=123]]

Fenom:

{set $pdfUrl = '!msGiftCardsCertificateLink' | snippet : ['order_id' => $order.id]}
<a href="{$pdfUrl}">Скачать PDF сертификата</a>
{'!msGiftCardsCertificateHtml' | snippet : ['order_id' => $order.id]}

PDF сертификат

Публичная точка входа:
assets/components/msgiftcards/certificate.php

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

— принимает только защищенный token;
— не использует открытый order_id в URL;
— извлекает данные сертификата по заказу;
— рендерит HTML из чанка msGiftCards.certificate;
— строит PDF через встроенный dompdf.

Короткие правила для PDF-шаблонов:

— Используйте UTF-8.
— Для кириллицы используйте DejaVu Sans, DejaVu Serif или DejaVu Sans Mono.
— Предпочитайте inline-стили.
— Не полагайтесь на сложный modern CSS.
— Не подключайте внешние CSS/JS.
— Избегайте position: fixed, сложных flex/grid-комбинаций и нестабильных web-font.
— Для изображений используйте локальные абсолютные пути внутри сайта, если они реально нужны.

Менеджер MODX

Страница Подарочные сертификаты содержит:

— вкладку сертификатов;
— вкладку истории операций;
— создание, редактирование, просмотр pdf сертификата, удаление, включение/отключение;
— поиск и фильтры;
— защиту от изменения/удаления сертификатов, у которых уже есть операции.