Документация
Sign3x — компонент для MODX 3, реализующий хранение, управление и подписание PDF-документов простой электронной подписью (ПЭП) в соответствии с Федеральным законом № 63-ФЗ «Об электронной подписи». Подпись фиксирует ФИО подписанта, должность, дату/время и уникальный SHA-256 хэш-ключ.
1. Требования
| Компонент | Версия | Примечание |
|---|---|---|
| MODX Revolution | 3.x | Обязательно |
| PHP | 8.1 или выше | Обязательно |
| MySQL / MariaDB | любая актуальная | Обязательно |
| pdoTools | любая актуальная | Необязательно — нужно только при использовании Fenom-шаблонов (&fenom=`1`) |
| FPDI + TCPDF | — | Входят в пакет — нужны только для визуального штампа в PDF |
2. Установка
- Установите пакет через MODX Менеджер пакетов (или скопируйте файлы вручную).
- После установки в базе данных автоматически создаются две таблицы:
sign3x_documents— документыsign3x_profiles— профили подписантов
- Перейдите в Системные настройки → Пространство имён: sign3x и настройте параметры (см. раздел Системные настройки).
- Обязательно создайте профили подписантов во вкладке «Сотрудники» для всех пользователей, которые должны иметь право подписи.
Права доступа. Панель управления Sign3x доступна только пользователям, прошедшим авторизацию в менеджере MODX (
mgr). Право подписи дополнительно ограничивается группами пользователей через настройкуsign3x_allowed_groups.
3. Системные настройки
Все настройки находятся в пространстве имён sign3x. Откройте: Администрирование → Системные настройки → фильтр «sign3x».
Основные
| Ключ настройки | По умолчанию | Описание |
|---|---|---|
sign3x_allowed_groups |
(пусто) | ID групп пользователей с правом подписи. Несколько значений через запятую: 1,5,12. Sudo-пользователи проверку группы не проходят — им достаточно иметь профиль подписанта. |
sign3x_secret_salt |
(пусто) | Секретная соль для формирования SHA-256 хэш-ключа. Задайте произвольную сложную строку. Никогда не меняйте после первого подписания — это делает существующие хэш-ключи невалидными. |
sign3x_upload_dir |
assets/sign3x/uploads/ |
Директория загрузки PDF-файлов относительно корня сайта. Должна быть доступна для записи веб-сервером. |
sign3x_filename_mode |
translit |
Формирование имени файла: translit — транслитерация, original — исходное имя, unique — уникальный UUID. |
sign3x_delete_files |
Да |
Удалять физические PDF-файлы при удалении документа из системы. |
sign3x_frontend_css |
assets/components/sign3x/css/frontend.css |
URL встроенных фронтенд-стилей. Если поле пустое — стили не подключаются. |
Визуальный PDF-штамп
| Ключ настройки | По умолчанию | Описание |
|---|---|---|
sign3x_pdf_stamp |
Нет |
Включить добавление визуального штампа в PDF при подписании. |
sign3x_pdf_stamp_mode |
overlay |
Режим: overlay — поверх последней страницы, newpage — отдельная страница «Лист ЭЦП». |
sign3x_stamp_title |
ЭЛЕКТРОННАЯ ПОДПИСЬ (ПЭП) | Заголовок штампа (оба режима). |
sign3x_stamp_page_title |
ЛИСТ ЭЛЕКТРОННОЙ ПОДПИСИ | Заголовок страницы подписи (newpage). |
sign3x_stamp_hash_label |
Программный ключ (SHA-256): | Подпись над хэш-ключом (newpage). |
sign3x_stamp_law_text |
Текст о соответствии ФЗ № 63-ФЗ | Текст о соответствии законодательству внутри рамки (newpage). |
sign3x_stamp_verify_text |
Текст о верификации | Текст под рамкой (newpage). |
sign3x_stamp_footer_text |
Сформировано автоматически системой Sign3x | Нижний колонтитул страницы (newpage). |
4. Администрирование
Панель управления Sign3x открывается через меню: Дополнения → Sign3x. Интерфейс состоит из двух вкладок.
4.1. Вкладка «Сотрудники»
Здесь управляются профили подписантов — записи, связывающие пользователя MODX с его ФИО и должностью.
| Поле | Описание |
|---|---|
| Пользователь MODX | Привязанный аккаунт из пользователей менеджера |
| ФИО | Полное имя подписанта (фиксируется в подписи) |
| Должность | Должность подписанта (фиксируется в подписи) |
Важно: Пользователь должен одновременно иметь профиль подписанта и входить в одну из групп, указанных в
sign3x_allowed_groups. При отсутствии хотя бы одного условия кнопка «Подписать» не отображается. Исключение — пользователи с флагом sudo: для них проверка членства в группе пропускается.
4.2. Вкладка «Документы»
Таблица всех загруженных документов с поиском, пагинацией и цветовой индикацией.
- Серая строка — черновик (status = 0, не подписан)
- Зелёная строка — подписан (status = 1)
Поиск выполняется по: названию документа, ФИО подписанта, хэш-ключу.
| Кнопка | Описание | Условие |
|---|---|---|
| Загрузить документ | Загружает PDF-файл и создаёт документ со статусом «Черновик» | Всегда доступна |
| Подписать | Открывает диалог подтверждения подписи | Только черновики + наличие права подписи у текущего пользователя |
| Удалить | Удаляет документ из БД (и файл, если включена настройка) | Всегда доступна; требует подтверждения |
4.3. Процесс подписания
- Нажмите кнопку «Подписать» рядом с нужным документом.
- В модальном окне отобразится:
- Название документа и ссылка для предпросмотра PDF
- Ваши ФИО, должность и дата/время подписания
- Предупреждение о необратимости действия
- Нажмите «Подтвердить». Система:
- Фиксирует ФИО, должность и точное время подписания в базе данных
- Генерирует уникальный SHA-256 хэш-ключ
- Устанавливает статус документа = «Подписан»
- Если включён PDF-штамп — добавляет визуальный штамп в файл
Подписание необратимо. Подписанный документ нельзя перевести обратно в статус «Черновик» средствами интерфейса.
5. Сниппет Sign3x
Сниппет выводит подписанные документы (status = 1) на страницах сайта с пиктограммой электронной подписи и информацией о подписанте.
5.1. Параметры сниппета
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
&id |
int | не задан | ID конкретного документа. Если задан — выводит только этот документ. |
&limit |
int | 20 |
Максимальное количество документов. Сортировка по дате подписания (новые первые). |
&tpl |
string | sign3x.doc.default |
Шаблон для одного документа: имя чанка или inline Fenom (@INLINE {$name}, требует &fenom=`1`). |
&fenom |
0 / 1 | 0 |
Обрабатывать шаблон через Fenom (pdoTools). При 1 используется синтаксис {$placeholder}. |
Плейсхолдеры в шаблонах
| Плейсхолдер | Описание |
|---|---|
id |
ID документа |
name |
Название документа (HTML-экранировано) |
file_url |
Полный URL до PDF-файла |
file_path |
Путь к файлу относительно корня сайта |
signer_fio |
ФИО подписанта |
signer_position |
Должность подписанта |
signed_at |
Дата и время подписания (дд.мм.гггг чч:мм:сс) |
hash_key |
SHA-256 хэш-ключ подписи |
aria_label |
Полный ARIA-текст для пиктограммы (доступность) |
assets_url |
URL директории assets/ — для ссылок на иконки SVG |
5.2. Примеры вызова
<!-- Вывод последних 20 подписанных документов, дефолтный шаблон -->
[[!Sign3x]]
<!-- С лимитом -->
[[!Sign3x? &limit=`5`]]
<!-- Один конкретный документ -->
[[!Sign3x? &id=`3`]]
<!-- Свой чанк (MODX-синтаксис) -->
[[!Sign3x? &tpl=`sign3x.doc.bs5`]]
<!-- Свой чанк (Fenom-синтаксис, требует pdoTools) -->
[[!Sign3x? &tpl=`sign3x.doc.bs5.fenom` &fenom=`1`]]
<!-- Inline Fenom-шаблон -->
[[!Sign3x? &tpl=`@INLINE <a href="{$file_url}">{$name}</a>` &fenom=`1`]]6. Готовые чанки
Компонент поставляется с шестью готовыми чанками-шаблонами:
| Чанк | CSS-фреймворк | Синтаксис | Примечание |
|---|---|---|---|
sign3x.doc.default |
Встроенный (frontend.css) | MODX [[+]] |
Чанк по умолчанию |
sign3x.doc.default.fenom |
Встроенный (frontend.css) | Fenom {$} |
Требует pdoTools |
sign3x.doc.bs5 |
Bootstrap 5 | MODX [[+]] |
— |
sign3x.doc.bs5.fenom |
Bootstrap 5 | Fenom {$} |
Требует pdoTools |
sign3x.doc.uikit3 |
UIKit 3 | MODX [[+]] |
— |
sign3x.doc.uikit3.fenom |
UIKit 3 | Fenom {$} |
Требует pdoTools |
Все чанки доступны для редактирования через Элементы → Чанки. Содержат: SVG-иконку подписи, всплывающую подсказку с ФИО/должностью/датой/хэшем, ссылку на PDF и ARIA-атрибуты для доступности.
7. Fenom-шаблоны
Fenom — движок шаблонов с синтаксисом {$var} и условиями {if}...{/if}, предоставляемый компонентом pdoTools. Не зависит от настройки MODX «Разрешить Fenom на страницах».
Когда использовать Fenom-чанки: когда нужна логика в шаблоне — условный вывод полей, циклы. Например, показывать должность только если она задана.
Сравнение синтаксиса
| Задача | MODX-синтаксис | Fenom-синтаксис |
|---|---|---|
| Вывод переменной | [[+name]] |
{$name} |
| Условный блок | — | {if $signer_position}...{/if} |
| Экранирование | Выполнено в PHP | Выполнено в PHP |
Пример Fenom-чанка с условием:
<div class="sign3x-document">
<span class="sign3x-stamp" aria-label="{$aria_label}">
<img src="{$assets_url}components/sign3x/img/sign3x.svg" width="32" height="32" alt="">
</span>
<a href="{$file_url}">{$name}</a>
{if $signer_position}
<small>{$signer_position}</small>
{/if}
</div>Вызов сниппета с Fenom-чанком:
[[!Sign3x? &tpl=`sign3x.doc.default.fenom` &fenom=`1`]]8. CSS и стили
Встроенные стили подключаются автоматически, если настройка sign3x_frontend_css не пуста. Чтобы отключить встроенные стили и использовать свой CSS — очистите настройку sign3x_frontend_css.
Ключевые CSS-классы
| Класс | Описание |
|---|---|
.sign3x-list |
Обёртка при дефолтном шаблоне: вертикальный flex-список с отступами |
.sign3x-document |
Один документ: flex-строка (иконка + ссылка) |
.sign3x-stamp |
Элемент-триггер иконки с всплывающей подсказкой |
.sign3x-stamp-icon |
SVG-иконка электронной подписи |
.sign3x-stamp-tooltip |
Всплывающая подсказка с данными подписи |
.sign3x-stamp-key |
Хэш-ключ (моноширинный шрифт, авто-перенос) |
.sign3x-doc-link |
Ссылка на PDF-документ |
9. Визуальный штамп в PDF
При включённой настройке sign3x_pdf_stamp после подписания в PDF-файл добавляется визуальный штамп. Библиотеки FPDI и TCPDF входят в состав пакета.
Режимы штампа
| Режим | Описание |
|---|---|
overlay |
Синий прямоугольный штамп поверх последней страницы документа (правый нижний угол) |
newpage |
Отдельная страница «Лист электронной подписи» добавляется в конец документа |
При успешном создании штампа оригинальный файл заменяется подписанной версией, путь обновляется в базе данных. При ошибке документ сохраняется без штампа — ошибка логируется в журнал MODX.
Все тексты в штампе настраиваются через системные настройки группы
sign3x_stamp_*.
10. Верификация подписи
Каждая подпись сопровождается уникальным SHA-256 хэш-ключом. Хэш формируется из следующих данных:
SHA-256(id|name|file_path|fio|position|signed_at|salt)| Компонент | Значение |
|---|---|
id |
ID документа в базе данных |
name |
Название документа |
file_path |
Путь к файлу на момент подписания |
fio |
ФИО подписанта из профиля |
position |
Должность подписанта из профиля |
signed_at |
Точная дата/время подписания (MySQL datetime) |
salt |
Секретная соль из настройки sign3x_secret_salt |
Хэш-ключ отображается:
- В таблице документов (вкладка «Документы»)
- В tooltip-подсказке на сайте при наведении на иконку подписи
- В PDF-штампе (если включён)
Не изменяйте
sign3x_secret_saltпосле первого подписания. Изменение соли сделает невозможным воспроизведение хэш-ключей и фактически аннулирует проверяемость всех существующих подписей.