pdoTools 2.14.0 и pdoTools3 3.1.0-pl: обновление для MODX 2 и MODX 3

Вышли новые версии pdoTools 2.14.0 и pdoTools3 3.1.0-pl — одного из наиболее популярных наборов инструментов для работы с выборками, меню, пагинацией и шаблонизацией в MODX.

Релизы продолжают развитие двух отдельных веток:

pdoTools 2.x — для проектов на MODX Revolution 2;
pdoTools3 3.x — для MODX Revolution 3 и PHP 8.1+.

В новой версии pdoTools3 появились дополнительные возможности для шаблонов pdoMenu, pdoPage и pdoCrumbs, новые Fenom-модификаторы для приведения типов, улучшена диагностика ошибок, обновлена интеграция с MiniShop3 и переработана инфраструктура тестирования и сборки пакета.

При этом ветка pdoTools 2.x также получила ряд полезных исправлений и улучшений.

Это не просто два одинаковых релиза с разными номерами: pdoTools3 постепенно становится самостоятельной веткой, ориентированной на современный стек MODX 3.

pdoTools 2.14.0

Версия 2.14.0 продолжает развитие стабильной ветки pdoTools для MODX Revolution 2.

pdoMenu: новый placeholder children
В pdoMenu добавлен новый placeholder children, доступный в шаблоне tplInner.

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

[[+children]]

Изменение связано с issue #306.

Fenom: array_merge включён по умолчанию

Функция array_merge теперь разрешена в Fenom по умолчанию.

Дополнительная настройка для её использования больше не требуется.

{$arr1|array_merge:$arr2}

Это особенно удобно при подготовке массивов параметров непосредственно в шаблоне.

Изменение связано с issue #356.

pdoTools: настройка pdotools_cache_path

Добавлена возможность задавать путь к файловому кэшу pdoTools через системную настройку: pdotools_cache_path

По умолчанию используется: {core_path}cache/pdotools

Это позволяет контролировать расположение кэша pdoTools/Fenom на проектах с нестандартной файловой структурой.

Изменение связано с issue #358.

pdoPage: свойства сниппета доступны в шаблонах пагинации

Свойства вызова pdoPage теперь доступны как placeholders внутри шаблонов пагинации.

Это даёт больше возможностей для построения кастомных вариантов пагинации без необходимости дублировать параметры.

Изменение связано с issue #392.

Исправления pdoPage

Исправлена работа ajaxMode в pdoPage.

В частности:

исправлена работа кнопки загрузки дополнительных результатов;
кнопка more скрывается, если новых результатов больше нет;
в режиме force кнопка корректно восстанавливается.

Это устраняет ситуацию, когда после последнего AJAX-запроса интерфейс продолжал показывать кнопку загрузки дополнительных результатов.

Также AJAX-запросы pdoPage теперь помечаются как connector mode через MODX_CONNECTOR_INCLUDED.

Это позволяет корректнее определять AJAX/connector-контекст выполнения запроса внутри MODX и сторонних дополнений.

Исправления pdoMenu

Исправлены PHP notices при работе pdoMenu с web-ссылками, у которых отсутствуют:

class_key;
content.

Это делает построение меню стабильнее для сайтов со смешанными типами ресурсов.

Исправления совместимости с PHP 8

В pdoTools исправлено приведение значения offset конфигурации к целому числу.

Это устраняет проблемы, связанные с более строгой типизацией в PHP 8.

Исправление pdoResources

Исправлена работа toSeparatePlaceholders, когда вызываемый сниппет возвращает строковое значение.

Это исправляет сценарии, в которых результат сниппета не является массивом данных.

pdoTools3 3.1.0-pl

pdoTools3 3.1.0-pl — версия pdoTools для современного стека MODX Revolution 3.

Она требует:

MODX Revolution 3;
PHP 8.1 или новее.

Документация теперь явно разделяет две линии: MODX 2 → pdoTools 2.x и MODX 3 + PHP 8.1+ → pdoTools3 3.x

Для pdoTools3 также используется отдельный репозиторий, что позволяет независимо развивать ветку для MODX 3.

Новые флаги строк

Одно из наиболее заметных изменений 3.1.0-pl — расширение набора информации, доступной непосредственно в шаблонах.

Общие флаги

В шаблонах pdoMenu, pdoPage и pdoCrumbs доступны:

isFirst — первый элемент;
isLast — последний элемент;
isActive — активный элемент.

Это позволяет переносить часть логики формирования HTML непосредственно в шаблон.

Дополнительные флаги pdoMenu

hasChildren;
hasChilds;
isHere;
isStart;
isCategory;
isInner.

Например, теперь шаблон меню может самостоятельно определить, есть ли у пункта дочерние элементы:

{if $hasChildren}
    ...
{/if}

Дополнительный флаг pdoPage

Для pdoPage появился: isSkip

Он позволяет учитывать состояние элемента при формировании результата.

Дополнительный флаг pdoCrumbs

Для pdoCrumbs добавлен: isHome

С его помощью в шаблоне breadcrumbs можно определить домашний элемент.

pdoMenu: children в tplInner

Как и в ветке 2.x, в pdoTools3 для pdoMenu доступен placeholder: [[+children]]

Он доступен в tplInner и позволяет удобно работать с дочерним содержимым пункта меню.

Новые Fenom casts

В pdoTools3 добавлены модификаторы для приведения типов:

boolval;
doubleval;
floatval;
intval;
strval.

Теперь преобразование типов можно выполнять непосредственно в Fenom:

{'1' | boolval}
{'3.14' | floatval}
{'3.14' | doubleval}
{'42abc' | intval}
{42 | strval}

Это особенно удобно при работе с данными из TV, JSON, API и сторонних компонентов.

array_merge разрешён по умолчанию

Функция array_merge теперь разрешена в Fenom без дополнительной настройки.

Например:

{set $arr1 = [2,15,55]}
{set $arr2 = [44,88,11]}

{$arr1|array_merge:$arr2}

Отдельно добавлять array_merge в pdotools_fenom_options больше не требуется.

pdotools_cache_path

Для pdoTools3 доступна системная настройка: pdotools_cache_path

По умолчанию: {core_path}cache/pdotools

Настройка определяет каталог файлового кэша pdoTools/Fenom.

Улучшена диагностика ошибок Fenom

Работа с ошибками компиляции и выполнения Fenom стала информативнее.

Теперь сообщение об ошибке содержит дополнительную информацию, позволяющую быстрее найти проблемный шаблон:

имя чанка или ресурса;
короткий фрагмент исходного кода;
путь к кэшу.

Было:

Unexpected token '+' in expression in ee058690d9fd7413748b95b0960e006b line 6, near '{var $limit = [[+' <- there

Стало:

[pdoTools][Fenom] compile error in chunk:tpl.product.row (#12)
resource:#42 (web:catalog/item)
cache name: modchunk/12
Unexpected token '+' in expression in chunk:tpl.product.row (#12) line 6, near '{var $limit = [[+' <- there
> 6: {var $limit = [[+limit]]}
Unprocessed MODX tag inside Fenom. Use {$limit} or parse MODX before Fenom.

Или

[pdoTools][Fenom] compile error in resource:#42 (web:catalog/item), template:#5
cache name: ee058690d9fd7413748b95b0960e006b
Unexpected token '+' in expression in resource:#42 (web:catalog/item), template:#5 line 6, near '{var $limit = [[+' <- there
> 6: {var $limit = [[+limit]]}
Unprocessed MODX tag inside Fenom. Use {$limit} or parse MODX before Fenom.

При этом принцип формирования ключа кэша не изменился — он по-прежнему основан на hash содержимого.

Для разработчиков это особенно полезно на больших проектах, где количество Fenom-шаблонов может исчисляться сотнями.

Кэш учитывает текущий контекст MODX

Изменена генерация ключей кэша результатов сниппетов.

Теперь при формировании ключа учитывается текущий контекст MODX.

Это особенно важно для мультиконтекстных сайтов:

web
ru
en
de

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

Для мультиконтекстных проектов это делает кэширование более предсказуемым и безопасным.

MiniShop3 вместо MiniShop2

Одно из ключевых изменений pdoTools3 — обновление работы дополнительных категорий товаров.

При разборе &parents дополнительные связи товаров теперь обрабатываются через модель MiniShop3:

MiniShop3\Model\msCategoryMember

Таким образом, pdoTools3 ориентирован на связку: MODX Revolution 3 + MiniShop3 + pdoTools

Это важное отличие от старой ветки, где соответствующая логика была связана с MiniShop2.

Удалена поддержка MiniShop2 в pdoTools3

Из pdoTools3 удалена специфичная для MiniShop2 логика.

В частности, больше не используются старые классы MiniShop2 и параметр: strong>&disableMS2

Вместо него используется: &disableMS3

Например: &disableMS3=1 отключает учёт дополнительных категорий MiniShop3 при обработке &parents.

Это важно учитывать при обновлении существующих проектов.

Если в коде проекта используются &disableMS2 или собственная логика, завязанная на классы MiniShop2, её необходимо проверить и адаптировать.

pdoCrumbs: исправление parents + showHome

Исправлена обработка строкового значения &parents в pdoCrumbs при включённом showHome.

В определённых сценариях вместо корректного значения мог формироваться пустой массив.

Теперь такой сценарий обрабатывается корректно.

pdoFetch: исправление предупреждения

Исправлено предупреждение, возникавшее при подготовке where/having для записи информации в лог.

Это устраняет лишние warnings в соответствующих сценариях использования pdoFetch.

pdoPage: исправление сравнения номера страницы

Исправлено строгое сравнение номера страницы.

Проблема была связана с типом значения, возвращаемого ceil(): в определённых случаях результат имел тип float, тогда как другая часть логики ожидала int.

Также исправлена работа с неопределённой переменной: $showLog

Сборка и тестирование

В pdoTools3 3.1.0-pl была заметно улучшена инфраструктура разработки.

Проект тестируется на нескольких версиях PHP:

PHP 8.1;
PHP 8.2;
PHP 8.3;
PHP 8.4.

Добавлены unit- и integration-тесты на базе PHPUnit 9.6.

Также используется GitHub Actions для автоматической проверки изменений и сборки transport-пакета.

Для контроля покрытия подключён strongcov.

Это важное изменение именно с точки зрения дальнейшего развития pdoTools3: изменения в коде теперь можно проверять на нескольких актуальных версиях PHP до выпуска новой версии.

Оптимизация production-пакета

Из transport-пакета pdoTools3 исключены тестовые деревья pdoTools и Fenom.

Это позволяет не включать в production-установку файлы, необходимые только для разработки и тестирования.

Также исправлена работа vendor autoload: если классы pdoTools уже загружены, дополнительная загрузка vendor autoload пропускается.

Обновление документации

Одновременно с выпуском pdoTools3 3.1.0-pl была актуализирована документация.

В ней теперь явно описывается разделение двух веток:

pdoTools 2.x для MODX 2;
pdoTools 3.x для MODX 3.

Документация также описывает новые возможности pdoTools3, включая:

флаги isFirst, isLast, isActive;
hasChildren и hasChilds;
isHere, isStart, isCategory, isInner;
isSkip;
isHome;
Fenom casts;
pdotools_cache_path;
&disableMS3;
интеграцию с msCategoryMember.

Также карточка компонента теперь может ссылаться сразу на оба репозитория — pdoTools и pdoTools3.

Что проверить перед обновлением

Если используется pdoTools 2.x

Обновление до 2.14.0 не требует перехода на MODX 3. Это очередной релиз ветки 2.x с исправлениями и улучшениями.

После обновления стоит проверить прежде всего собственные шаблоны pdoPage, pdoMenu и сценарии, использующие toSeparatePlaceholders.

Если используется pdoTools3

Перед обновлением необходимо убедиться, что проект работает на:

MODX Revolution 3 + PHP 8.1+

Также следует проверить использование MiniShop2.

Если проект использует: &disableMS2

для pdoTools3 его необходимо заменить на: &disableMS3

Также стоит проверить собственные Fenom-модификаторы, если проект самостоятельно регистрирует новые функции приведения типов.

Итоги

pdoTools 2.14.0 — аккуратное обновление стабильной ветки с исправлениями pdoPage, pdoMenu, pdoResources, улучшениями Fenom и возможностью настройки пути кэша.

pdoTools3 3.1.0-pl — более заметный шаг в развитии инструментария для MODX 3.

Главные изменения новой версии:

поддержка PHP 8.1+;
тестирование на PHP 8.1–8.4;
PHPUnit 9.6;
unit- и integration-тесты;
автоматическая сборка через GitHub Actions;
новые флаги строк для pdoMenu, pdoPage и pdoCrumbs;
новые Fenom casts;
array_merge включён по умолчанию;
pdotools_cache_path;
более информативные ошибки Fenom;
контекст MODX учитывается при формировании ключа кэша;
дополнительные категории работают через MiniShop3\Model\msCategoryMember;
удалена MiniShop2-специфика;
вместо &disableMS2 используется &disableMS3;
улучшена сборка production transport-пакета.

В результате pdoTools3 всё больше отделяется от исторического наследия pdoTools 2.x и формирует собственную современную базу для MODX Revolution 3.

Особенно логично это выглядит в связке с MiniShop3: современный MODX, PHP 8.1+, MiniShop3 и pdoTools3 теперь развиваются как единый актуальный стек, без необходимости сохранять внутри новой ветки совместимость со старым MiniShop2.

Ссылки

Поддержка Open Source

Весь этот проект развивается благодаря Open Source и поддержке сообщества.

Разработка новых возможностей, исправление ошибок, поддержка совместимости с новыми версиями PHP и MODX, тестирование, документация, разбор issues и pull request'ов — всё это требует большого количества времени.

pdoTools, pdoTools3, MiniShop3 и другие проекты экосистемы MODX развиваются открыто и доступны сообществу. При этом значительная часть работы над ними выполняется в свободное от коммерческих проектов время.

Если вы используете эти проекты в своих сайтах и магазинах, они помогают вам зарабатывать, экономить время разработки или просто хотите, чтобы MODX и его Open Source-экосистема продолжали развиваться — можно поддержать разработку донатом.
Даже небольшой регулярный донат помогает выделять больше времени на:

развитие Open Source-проектов;
выпуск новых версий и функциональности;
исправление ошибок и технический долг;
поддержку актуальных версий PHP и MODX;
развитие документации;
разбор issues и pull request'ов;
создание новых бесплатных дополнений и инструментов.

Если хотите поддержать эту работу:

Спасибо всем, кто использует, тестирует, создаёт issues, отправляет pull request'ы, пишет документацию и поддерживает проекты финансово.

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