Новый тип дополнений: mmxDatabase и mmxForms

Привет, друзья, давно не виделись!

Прошло уже более 3х лет, как я перестал активно работать с MODX и занялся своим проектом Vesp. За это время я создал много разных сайтов и библиотек, неплохо освоил современные технологии, а теперь возвращаюсь порадовать сообщество MODX.

Почти год назад я уже написал заметку о фундаментальной проблеме в 3й версии MODX, и даже предложил готовый вариант её решения, но никакой реакции это не вызвало. Судя по количеству закачек (целых 10!), никто даже не попробовал установить новое дополнение и посмотреть, как оно работает.

Плюсом к этому добавились мои разговоры с европейскими коллегами на недавнем митапе в Швейцарии, из которых я вынес, что никто ничего менять не планирует.

А у меня есть свободное время, так что я решил немного подорвать экосистему новым типом дополнений, которые должны быть настолько хороши, чтобы заставить вас использовать Composer с MODX 3.

Начнём с демонстрации работы:

Composer

По какой-то особенной причине авторы MODX не дают работать с Composer в MODX по умолчанию. Для этого вам нужно или создать новый проект через composer create-project, или установить его из Git, или просто скачать composer.json из репозитория.

Последний вариант самый простой для уже существующих сайтов:

cd /to/modx/root/
wget https://raw.githubusercontent.com/modxcms/revolution/v3.0.4-pl/composer.json

Обратите внимание на версию системы в адресе.

После этого можно обновить зависимости системы, чтобы проверить как всё работает:

composer update

Кстати говоря, это неплохой способ исправлять баги в зависимостях без обновления самой системы.

mmxDatabase

Для новых дополнений нужен и новый префикс, так что я выбрал mmx — то есть Modern MODX. Скромненько и со вкусом.

Первым делом я написал mmxDatabase, который добавляет возможность работы с основными таблицами MODX через Eloquent. Про это уже давно и много где говорили, но дальше примеров «смотрите как можно» дело до сих пор не зашло.

Ну а теперь есть готовый пакет, который можно установить в MODX 3 и работать с БД в обход xPDO. Внутри лежат готовые модели со связями, которые можно использовать в любом месте системы.

<?php

$resources = \MMX\Database\Models\Resource::query()
    ->with('Template:id,templatename')
    ->with('TvValues')
    ->where('published', true)
    ->get();
foreach ($resources as $resource) {
    print_r($resource->toArray());
}

Все модели написаны вручную (могут быть ошибки) и со временем я планирую добавлять новые и обновлять старые.

Важно понимать, что это отдельные модели, они никак не связаны с xPDO и его схемами. Внутри не вызываются никакие события, не очищается кэш, не удаляются связи и т.д. Так что, с одной стороны, вы получаете высокоскоростной удобный инструмент для работы с БД, а с другой нужно понимать, что именно вы делаете и зачем.

В любом случае, знания по работе с Eloquent вам пригодятся в жизни гораздо больше, чем по xPDO.

mmxForms

Когда я поделился своей идей о создании новых дополнений с ребятами из Pixmill, в которой я работаю, они предложили мне сделать что-то с FormIt. Мол, сейчас у него запутанная система хуков, чанков, трудно отлаживать отправку почты и вообще он страницу перезагружает для работы, фи!

Я решил подойти к вопросу творчески, и просто выкинул ручную вёрстку форм, заменив их конструктором Vueform.

Логика такая:

1. Устанавливаем дополнение через Composer
2. Создаём форму в онлайн конструкторе, настраиваем там правила валидации и остальные параметры
3. Копируем получившуюся схему в mmxForms
4. Выводим форму на сайте
5. Ура, всё работает!

Понятное дело, что можно и вручную написать схему формы, почитав документацию Vueform — пользователям MIGX это должно быть раз плюнуть.

Конечно, коллеги из Pixmill мне сразу предложили проверить, как оно будет работать с реальной формой — и дали пример с текущего проекта в разработке. Минут за 10 я её сгенерировал, никаких проблем:

(кликаем на картинку)


Вообще, судя по обилию кнопочек и переключаетелей в онлайн конструкторе, ограничений у него нет.

Установка и удаление

mmxForms еще в разработке и будет там, полагаю, еще долго. Уж больно много возможностей использования мне нужно предусмотреть.

Например, там можно загружать файлы и выводить select с данными из БД, что я постараюсь добавить в следующем обновлении.

А пока можно потестить стандартный функционал: создание и отправку формы, вместе с email.

Ставим так:

composer require mmx/forms
composer exec mmx-database install # это если вы еще не устанавливали это дополнение
composer exec mmx-forms install

Вызываемые скрипты поставляются вместе с дополнениями и сами знают, что делать. В данном случае это будет создание namespace, пункта в меню, плагина, сниппета и линковка директорий с файлами. Файлы из core/vendor/mmx/* не копируются в MODX, а добавляются через символические ссылки.


Ах, да, еще и создание нужных таблиц через миграции Phinx.

Удаляем так же, но в обратном порядке:

composer exec mmx-forms remove
composer exec mmx-database remove # если не установлено отдельно, тоже нужно удалить
composer remove mmx/forms

Здесь тонкий момент в том, что если mmx/database установлен автоматически при установке mmx/forms, то Composer его так же автоматически и удалит. А раз он был установлен в MODX, то перед удалением нужно запустить и его скрипт.

Если же вы установите mmx/database как отдельную зависимость в composer.json, то удалять его не нужно.

Защиты «от дурака» пока что нет. В случае, если вы забудете правильно удалить зависимость, и сайт упадёт — никаких проблем, просто установите её обратно и удалите как положено.

Вы же всё равно это делаете из консоли сервера и нерабочая админка вам никак не помешает всё починить.

Принцип работы

mmxDatabase работает очень просто — добавляет себя как системный сервис в MODX, инициализирует глобальный экземпляр Eloquent, используя системные настройки и всё — дальше любой желающий может с ним работать.

То есть, этот сервис стартует каждый раз при инициализации ядра, так как я полагаю, что вы хотите работать с Eloquent из любого места, без ручной инициализации. Поэтому и так важно запустить его скрипт удаления, перед реальным удалением через Composer.

У mmxDatabase нет ни сниппетов, ни плагинов — ничего, только namespace, для загрузки файла bootstrap.php.

А вот у mmxForms есть свой раздел в админке, который по сути является местным филиалом Vesp внутри MODX. Я даже выпустил новую версию vesp/core 4, чтобы оно нормально работало с зависимостями MODX 3.

Ядро Vesp здесь нужно для реализации нормального API по стандарту PSR-7, с правильными типами запросов и кодами ответов.


Плагин дополнения реагирует на адрес /mmx-forms/ в начале запроса и пытается обработать запрос. Работает это как внутри админки (требует быть авторизованным в контексте mgr), так и снаружи для отправленных форм.

У всех mmx дополнений будет свой namespace и, соответственно, свой адрес для запросов. Так мы внезапно получаем настоящий API для работы с дополнением (если вдруг кому-то надо).

Вообще у дополнения на данный момент 5 таблиц:

• mmx_forms_forms — собственно, формы с настройками
• mmx_forms_submissions — данные, отправленные юзерами из этих форм
• mmx_forms_emails — письма, сгенерированные из данных, если это указано в настройках формы
• mmx_forms_tokens — одноразовые токены форм, см. ниже
• mmx_forms_migrations — служебная таблица для проведения миграций этого дополнения

Борьба со спамом

Кстати, насчёт запросов на отправку форм. Вот как они выглядят снаружи, на публичной части сайта:



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

Но чтобы спамеры не завалили вас отправкой форм на прямой адрес API прямо сейчас, предусмотрена система токенов. При каждом выводе формы на сайте генерируется одноразовый код, который удаляется или после её отправки, или через 12 часов.

То есть, чтобы слать вам спам без проверки, нужно каждый раз как-то получать этот уникальный токен — то есть загружать страницу с формой и выковыривать его оттуда.

Но даже если и это не поможет, то есть еще системная настройка mmx-forms.email-on-submit, которую можно отключить, чтобы письма не отправлялись сразу после отправки формы. А вы можете позже проверять присланные значения самостоятельно, своим скриптом, и удалять неправильные вместе с подготовленными письмами.

А потом уже отправлять оставшиеся в живых письма через консольный скрипт:

composer exec mmx-forms emails

Кстати говоря, у дополнения есть нормальный консольный интерфейс — так что в будущем могут быть добавлены и новые команды.

Админка

Тут уж я себя не ограничивал.

Современное SPA приложение на Vue 3, Bootstrap-Vue-Next, Bootstrap-SCSS и моих компонентах из Vesp, адаптированных для MODX.







Всё это собирается Vite раздельно для фронта и бэка с общими зависимостями.

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

В любом случае, всё сделано по последнему слову техники, насколько я себе это представляю. И Vue Router работает и сохраняет вам в админке MODX прямые ссылки на модальные окошки.

Даже файл с лексиконами выглядит не как у всех.

Вообще я подумал, что уже много лет дополнения для MODX пишутся по одним лекалам, даже если те и устарели. Вот зачем нам, например, тупо добавлять записи в лексикон поштучно? Мало того, что это неудобно, так еще и в глазах рябит.

У меня вот так:

Можно сворачивать блоки с текстом и вообще, лучше понимать что к чему относится.

Кстати говоря, пришлось написать и свою утилиту useLexicon для работы с этими записями из Vue, в которой можно использовать и склонения как у Vue-i18n.

В общем, тут много чего сделано, и будет сделано еще. Планирую позже всё это выделить в отдельную библиотеку для более лёгкой работы, как уже сделал с @vesp/frontend.

Преимущества

Зачем же я это всё вообще затеял?

1. Мы решаем фундаментальную проблему с дублированием зависимостей, когда каждый транспортный пакет MODX может притащить свою версию популярной библиотеки в общее пространство имён, и что-нибудь этим сломать.

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

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

2. Отказ от транспортных пакетов.

Да-да, тех самых, которые устанавливаются в админке и были придуманы еще до изобретения Composer (не шучу).

У них как-бы есть версионирование, но если вы вручную не прописали в новой версии, что ей надо почистить какие-то старые файлы, то они останутся — и могут мешать работе.
Так же все установленные версии хранятся в core/packages, чтобы вы могли на них откатиться при желании, и занимают там место. Конечно, их можно переодически чистить, но и откатиться тогда никуда не получится.

Так как эти пакеты устанавливаются из админки, то при возникновении какой-то проблемы вы можете получить нерабочий сайт, и, соответственно, нерабочую админку. И невозможность откатить установку проблемного дополнения. Прикол с бесконечно висящим окном установки широко известен.

3. Независимость от провайдеров пакетов.

Всё работет через промышленный стандарт: github.com и packagist.org — больше никто не нужен.

Более того, можно подписаться на обновления кода в Github и получать уведомления о релизе новой версии. А потом идти на сайт и делать composer update. Новые версии публикуются путём создания релиза в репозитории, а там можно еще и расписать все изменения красиво.

4. Актуальность технологий

Этот способ решает и ещё одну большую проблему системы — отток мозгов. Вы уже могли заметить, что как только разработчик развивается достаточно, чтобы начать работать с общепринятыми решениями в мире PHP (Symfony, Laravel), то ему быстро становится скучно и он уходит.

За последние годы ушли, кажется, уже все серьёзные двигатели прогресса в русскоговорящем сообществе. А те, которые не совсем еще ушли, забегают иногда в комментарии, написать что-то типа «я уже давно с MODX не работаю, но вроде надо вот так».

Это не претензия, это медицинский факт. Нормальному разработчику в MODX ловить нечего, тут всё давно уже умерло, в плане технологий.

Надеюсь, что mmx дополнения смогут заинтересовать кого-то из старых мастеров вернуться к разработке для MODX. Тем более, что минимальная версия PHP для работы с mmxForms — 8.1.

Как вы понимаете, поле здесь непаханное — можно переписать вообще все компоненты на новом технологическом уровне, если у сообщества будет такое желание и поддержка.

Заключение

Честно говоря, я немного утомился всё это разрабатывать за последние 2 недели (при том, что использовал уже готовые наработки из проекта sterc/csp), так что решил поделиться с вами промежуточным результатом. Вроде как зарелизить, почитать отзывы с предложениями, и дорабатывать уже по ним.

Как вы понимаете, в работе с формами совершенство недостижимо. Будет обновляться и Vueform, и хотелки пользователей MODX. Например, недавно видел где-то вопрос, как можно к отправляемому письму через FormIt подцепить левый, отдельно сгенерированный файл?

Так что я постарался сделать максимально прочный и надёжный фундамент, притащив сюда все свои любимые технологии, не касаясь самого MODX, по возможности. Я не хочу работать с ExtJS, не хочу работать с xPDO, и тем более использовать практики, которые старше моего сына.

Я хочу получать от работы удовольствие, а не ощущать, что система мне мешает. Этот проект я разрабатываю в Docker, здесь всё на файлах, таблицы меняются миграциями, фронт обновляется через hot module reload, и всё такое прочее. MODX сейчас, по сути, просто оболочка для запуска моего приложения.

Что будет дальше — зависит от вас. Если инициатива mmx встретит одобрение, будут пользователи, запросы на улучшения и прочий интерес — буду продолжать. Возможности у меня пока есть, да и благодаря новому подходу, мне очень легко перетаскивать свой код из Vesp в MODX и обратно.

Пока что план для новых версий такой:

• Сделать поддержку загрузки файлов и отправки их на почту
• Добавить систему плагинов для модификации отправляемых форм и писем
• Сделать базовую валидацию на бэкенде, используя схему формы из javascript

Проходите в репозиторий, пробуйте установить новое дополнение по инструкции (желательно, на тестовом сайте), пишите отзывы, ставьте звёздочку.

А если лень устанавливать, просто поиграйтесь с онлайн конструктором Vueform и представьте, что такие формы можно будет выводить на вашем сайте.

Обновлено 24.03.2024

Дополнение можно попробовать и на modhost.pro. Выбираем PHP 8.1 и тариф «Тестовый».

Несмотря на указанную версию PHP, в консоли всё равно по будет PHP 7.0, так что правильные команды выглядят вот так:

mkdir ~/bin
ln -s /usr/bin/php8.1 ~/bin/php
source ~/.profile

cd ~/www
wget https://raw.githubusercontent.com/modxcms/revolution/v3.0.5-pl/composer.json

composer require mmx/forms
composer exec mmx-forms install

Фокус в том, чтобы создать ссылку на нужную версию PHP в локальной директории ~/bin, и тогда все консольные скрипты будут использовать именно её.

composer require mmx/database

require_once dirname(__FILE__) . '/vendor/autoload.php';
class_alias(\modX::class, 'MODX\\Revolution\\modX');
$mmxDatabase = new MMX\Database\App($modx);

$resource = \MMX\Database\Models\Resource::find(1);
print_r($resource->toArray());

./composer.json has been updated
Running composer update mmx/forms
Loading composer repositories with package information
Updating dependencies
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - illuminate/support[v10.0.0, ..., v10.16.1] require nesbot/carbon ^2.62.1 -> found nesbot/carbon[2.62.1, ..., 2.x-dev] but it conflicts with your root composer.json require (^3.3).
    - illuminate/support[v10.17.0, ..., 10.x-dev] require nesbot/carbon ^2.67 -> found nesbot/carbon[2.67.0, ..., 2.x-dev] but it conflicts with your root composer.json require (^3.3).
    - vesp/core 4.0.0 requires illuminate/events ^v10.15.0 -> satisfiable by illuminate/events[v10.15.0, ..., 10.x-dev].
    - mmx/forms[dev-main, 1.0.0, ..., 1.3.0] require vesp/core ^4.0 -> satisfiable by vesp/core[4.0.0].
    - illuminate/events[v10.47.0, ..., 10.x-dev] require illuminate/support ^10.0 -> satisfiable by illuminate/support[v10.0.0, ..., 10.x-dev].
    - Root composer.json requires mmx/forms * -> satisfiable by mmx/forms[dev-main, 1.0.0, ..., 1.3.0, 9999999-dev].

Use the option --with-all-dependencies (-W) to allow upgrades, downgrades and removals for packages currently locked to specific versions.
You can also try re-running composer require with an explicit version constraint, e.g. "composer require mmx/forms:*" to figure out if any version is installable, or "composer require mmx/forms:^2.1" if you know which you need.

Installation failed, reverting ./composer.json and ./composer.lock to their original content.